


[ 美 ] 米 格 尔 * 格 林 贝 格 著 


安道 译 


加 中 国 工 信 出 版 集团 


以 


人 民 邮 电 出 版 社 


POSTS & TELECOM PRESS 





安道 

专注 于 现代 计算 机 技术 的 自 

由 翻译 ， 译 有 《流畅 的 

Python》 《Python 网 络 编程 
攻略 》 《Ruby on Rails 教 程 》 等 书 。 


效 字 有 版权 声明 


图 灵 社 区 的 电子 书 没有 采用 专 有 客 
户 端 ， 您 可 以 在 任意 设备 上 ， 用 自 
己 喜 欢 的 浏览 器 和 PDF 阅读 器 进行 
阅读 。 

但 您 购买 的 电子 书 仅 供 您 个 人 使 用 ， 
未 经 授权 ， 不 得 进行 传播 。 

我 们 愿意 相信 读者 具有 这 样 的 良知 
和 觉悟 ， 与 我 们 共同 保护 知识 产权 。 


如 果 购 买 者 有 侵权 行为 ， 我 们 可 能 
对 该 用 户 实 施 包括 但 不 限于 关闭 该 
帐号 等 维权 措施 ， 并 可 能 追究 法 律 
责任 。 


BE 人 图 录 答 房 设 计 从 书 


Flask Web 开 发 : 
基于 Python 的 Web 应 用 开发 实战 〈 第 2 版 ) 


Flask Web Development: 
Developing Web Applications with Python, 9econd Edition 





[ 美 ] 米 格 尔 。 格林 贝 格 车 
安道 译 


Beijing . Boston . Farnham . Sebastopol. Tokyo OREILLY® 


O'Reilly Media, Inc. 授 权 人 民 邮 电 出 版 社 出 版 


人 人民 邮 电 出 版 社 
北 京 


图 书 在 版 编目 (C I P ) 数据 




















Flask Web 开 发 : 基于 Python 的 Web 应 用 开发 实战 : 
第 2 版 / (天 米 格 尔 。 格 林 贝 格 (Miguel Grinberg) 车 ; 
安道 译 ， 一 北京 : 人 民 邮 电 出 版 社 ，2018.8 

(图 灵 程 序 设计 丛书) 

ISBN 978-7-115-48945-6 


TI， OF… 本 ， 米 … 四 安 … JI， 外 软件 工具 一 程序 
设计 IV. @DTP311. 561 






























































中 国 版 本 图 书馆 CIP 数 据 核 字 (2018) 第 165766 号 











内 容 提 要 
本 书 共 分 三 部 分 ， 全 面 介 绍 如 何 基于 Python 微 框架 Flask 进行 Web 开发 。 第 一 部 分 是 
Flask 简介 ,介绍 使 用 Flask 框 架 及 扩展 开发 Web 程 序 的 必 备 基础 知识 es 个 实例 ， 
真正 带领 大 家 一 步 步 开 发 完整 的 博客 和 社交 应 用 Flasky， 从 而 将 前 述 知识 融会 贯通 ， 付 诸 实践 。 
卉 于 站 分 介绍 了 安检 应用 过 本 必须 敌 虑 的 事项 ， 如 单元 测试 策略 、 性 能 分 析 技 术 、Flask 程序 的 
部 署 方 式 等 。 第 2 版 针对 Python 3.6 全 面 修订 。 
本 书 适 合 熟悉 Python 编程 ， 有 意 通过 Flask 全 面 掌握 Web 开发 的 程序 员 学 习 参 考 。 
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与 其 他 框架 相 比 ，Flask 之 所 以 能 脱颖而出 ， 原 因 在 于 它 让 开发 者 做 主 ， 使 其 对 应 用 拥有 


全 面 的 创意 控制 。 或 许 你 听 过 “和 框架 斗争 ” 
的 解决 方案 不 受 框架 官方 支持 时 就 会 发 生 这 种 情况 。 
不 同 的 用 户 身份 验证 方法 。 但 是 ， 这 种 偏离 框架 开发 者 设 定 路 线 的 做 法 往往 会 给 你 带 来 很 


多 有 诸 烦 。 


这 一 说 法 。 在 大 多 数 框架 中 ， 当 你 决定 使 用 

















你 可 能 想 使 用 不 同 的 数据 库 引擎 或 者 











Flask 就 不 一 样 了 。 你 喜欢 关系 型 数据 库 ? 很 好 。Flask 支持 所 有 的 关系 型 数据 库 。 或 许 你 


更 喜欢 使 用 NoSQL 数据 库 ? 没 








器 题 ，Flask 也 支持 。 


想 使 用 自己 开发 的 数据 库 引 擎 ? 根本 


























用 不 到 数据 库 ? 依然 没 问题 。 在 Flask 中 ， 你 可 以 自主 选择 应 用 的 组 件 ， 如 有 果 找 不 到 合适 





的 ， 还 可 以 自己 开发 。 就 这 么 简 








Flask 之 所 以 能 给 用 户 提 供 这 么 大 的 自由 度 ， 关 键 在 于 其 开发 伊始 就 考虑 到 了 扩展 性 。 
Flask 提供 了 一 个 强健 的 核心 ， 其 中 包含 每 个 Web 应 用 都 需要 的 基本 功能 ， 而 其 他 功能 则 

















交 给 生态 系统 中 众多 的 第 三 方 扩展 一 一 


本 书 将 展示 我 自己 使 用 Flask 开发 Web 应 用 的 工作 流程 。 我 不 觉得 这 是 使 用 Flask 开发 应 
用 的 唯一 正确 方式 。 你 应 该 把 我 的 选择 作为 一 种 推荐 方式 ， 而 不 是 真理 。 























然 ， 你 也 可 以 自行 开发 。 








大 部 分 软件 开发 类 图 书 都 使 用 短 而 精 的 示例 代码 ， 扳 立地 演示 所 介绍 技术 的 功能 ， 让 读者 
自己 去 思考 如 何 使 用 “胶水 ”代码 把 这 些 不 同 的 功能 组 合 起 来 ， 开 发 出 完整 可 用 的 应 用 。 
本 书 采用 了 完全 不 同 的 方式 。 本 书 中 的 示例 代码 都 摘自 同一 个 应 用 ， 开 始 时 很 简单 ， 后 续 
逐 章 进行 扩展 。 最 初 这 个 应 用 只 有 几 行 代码 ， 最 后 将 变 成 功能 完善 的 博客 和 社交 网 络 应 用 。 

















面 回 的 读者 群 








要 想 更 好 地 理解 本 书 内 容 ， 你 需要 具备 一 定 的 Python 编程 经 验 。 阅 读本 书 并 不 要 求 你 了 解 








Flask 的 相关 知识 ， 但 你 最 好 理解 Python 的 一 些 概念 ， 比 如 包 、 模 块 、 图 数 、 装 饰 左 和 面 
向 对 象 编程 。 熟 悉 异 常 处 理 ， 知 道 如 何 从 栈 跟 踪 中 分 析 问 题 也 有 助 于 理解 本 书 。 


学 习 本 书 示例 代码 时 ， 你 大 部 分 时 间 都 将 在 命令 行 中 操作 。 因 此 ， 你 应 该 能 够 熟练 使 用 自 











己 操 作 系统 中 的 命令 行 。 
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现代 Web 应 用 都 不 可 避免 地 需要 使 用 HTML、CSS 和 JavaScript。 本 书 开发 的 示例 应 用 当 
然 也 用 到 了 这 些 技术 ,但 本 书 没 有 对 其 进行 详细 介绍 ， 也 没有 说 明 应 该 如 何 使 用 。 因 此 ， 
如 果 你 想 开发 完整 的 应 用 ， 且 无 法 向 精通 客户 端 技 术 的 开发 者 寻求 帮助 ， 那 就 需要 对 这 些 
语言 有 一 定 程度 的 了 解 。 

本 书 配套 的 应 用 是 开源 的 ， 我 把 它 上 传 到 GitHub 了 。 虽 然 你 可 以 从 GitHub 上 下 载 ZIP 或 
TAR 格式 的 源码 ， 但 我 还 是 强烈 建议 你 安装 Git 客户 端 ， 以 便 熟 悉 怎么 使 用 源码 版 本 控制 
系统 (至 少 要 知道 如 何 直接 从 仓库 中 克隆 源码 以 及 如 何 切换 到 应 用 的 不 同 版 本 )。 接 下 来 
的 “如 何 使 用 示例 代码 ”部 分 会 介绍 几 个 你 需要 知道 的 命令 。 你 或 许 也 希望 在 自己 的 项 目 
中 使 用 版 本 控制 ， 那 就 把 本 书 作 为 学 习 Git 的 一 个 契机 吧 。 


最 后 要 说 明 的 是 ， 本 书 并 不 是 完整 且 详 尽 的 Flask 框架 手册 。 虽 然 本 书 介绍 了 Flask 的 大 部 
分 功能 ， 但 你 还 需要 配合 使 用 Flask 官方 文档 (http://flask.pocoo.org/)。 


本 书 结构 
本 书 分 为 三 部 分 。 
第 一 部 分 “Flask 简介 简要 介绍 如 何 使 用 Flask 框架 及 一 些 扩展 开发 Web 应 用 。 


。 第 1 章 说 明 如 何 安装 和 设置 Flask 框架 ; 

。 第 2 章 通过 一 个 简单 的 应 用 介绍 如 何 使 用 Flask; 
。 第 3 章 介绍 如 何在 Flask 应 用 中 使 用 模板 ; 

。 第 4 章 介 绍 Web 表单 ; 

。 第 5 章 介绍 数据 库 ; 
。 第 6 章 介绍 如 何 实现 电子 邮件 支持 ; 

。 第 7 章 提供 一 个 可 供 中 大 型 程序 使 用 的 应 用 结构 。 


第 二 部 分 “实例 : 社交 博客 应 用 开发 Flasky， 这 是 我 为 本 书 开发 的 开源 博客 和 社交 网 络 应 用 。 


。 第 8 章 实 现 用 户 身份 验证 系统 ; 

。 第 9 章 实现 用 户 角色 和 权限 ， 

。 第 10 章 实现 用 户 资料 页 

。 第 11 章 开发 博客 界面 ， 

。 第 12 章 实现 关注 功能 ; 

。 第 13 章 实现 博客 文章 的 用 户 评论 功能 

。 第 14 章 实现 应 用 编程 接口 (API，application programming interface ) 。 

第 三 部 分 成 功 在 望 介 绍 与 开发 应 用 没有 直接 关系 ， 但 在 应 用 发 布 之 前 要 考虑 的 事 
。 第 15 章 详细 说 明 各 种 单元 测试 策略 ， 

。 第 16 章 简要 介绍 性 能 分 析 技 术 ，; 

。 第 17 章 说 明 Flask 应 用 的 部 署 方式 ， 包 含 传统 方式 、 云 方式 和 基于 容器 的 方式 ; 
。 第 18 章 列 出 其 他 资源 。 
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如 何 使 用 示例 代码 


本 书 使 用 的 示例 代码 可 从 GitHub 上 下 载 ': https://github.com/miguelgrinberg/flasky。 

这 个 仓库 的 提交 历史 是 精心 设计 的 ， 与 本 书 介绍 的 功能 顺序 一 臻 。 使 用 这 份 代码 时 ， 我 建 
议 你 从 最 早 的 提交 开始 ， 跟 随 本 书 内 容 的 进度 ， 向 前 推移 提交 列表 。 另 外 ， 你 还 可 以 从 
GitHub 上 下 载 每 次 提交 代码 后 得 到 的 ZIP 或 TAR 文件 。 
如 果 你 决定 使 用 Git 操作 源码 ， 那 么 首先 要 安装 Git 客户 端 (可 以 从 http://git-scem.com/ 下 
载 )。 使 用 Git 下 载 本 书 示例 代码 的 命令 如 下 : 


$ git clone https://github.com/miguelgrinberg/flasky.git 


git clone 命令 从 GitHub 上 下 载 源码 ， 安 装 到 当前 目录 下 的 flasky 文件 夹 中 。 这 个 文件 夹 
中 不 仅 有 源码 ， 还 有 一 个 包含 应 用 完整 修改 历史 的 Git 仓库 。 
第 1 章 会 要 求 你 检 出 应 用 的 初始 发 布 版 本 ， 然 后 在 适当 的 时 候 再 指示 你 向 前 推进 查看 提交 
历史 。 切 换 提交 历史 的 Git 命令 是 git checkout。 下 面 举 个 例子 : 


$ git checkout 1a 


上 述 命令 中 的 1a 代表 一 个 标签 (tag)， 是 项 目 中 某 次 提交 历史 的 名 称 。 这 个 仓库 的 标签 根 
据 本 书 的 章节 命名 ， 因 此 本 例 中 的 1a 表示 第 1 章 使 用 的 初始 版 本 。 大 多 数 章 都 不 止 使 用 
一 个 标签 ， 例 如 5a 和 5b 等 分 别 对 应 第 5 章 中 用 到 的 不 同 版 本 。 
执行 上 述 git checkout 命令 后 ，Git 会 显示 一 个 提醒 消息 ， 指 出 你 在 “ 抓 立 的 HEAD” 状 
态 。 这 表明 你 不 在 能 接受 新 提交 的 代码 分 支 上 ， 而 是 在 查看 项 目 提交 历史 中 的 某 次 提交 。 
不 要 被 这 个 消息 吓 着 ， 但 是 要 注意 ， 一 旦 你 在 这 个 状态 下 修改 了 文件 ， 便 不 能 再 执行 git 
checkout 命令 ， 因 为 Git 不 知 如 何 处 理 你 所 做 的 改动 。 因 此 ， 为 了 能 继续 跟着 本 书 操作 ， 
你 要 把 改动 的 文件 还 原 到 最 初 的 状态 。 最 简单 的 方法 是 使 用 git reset 命令 : 

$ git reset --hard 
这 个 命令 会 撤销 本 地 修改 ， 所 以 在 执行 之 前 ， 你 要 保存 所 有 不 想 丢 失 的 改动 。 
除了 检 出 应 用 源码 的 不 同 版 本 ， 你 可 能 还 需要 进行 一 些 设置 。 例 如 ， 有 了 时 需要 安装 额外 的 
Python 包 ， 或 者 升级 数据 库 。 需 要 执行 这 些 操作 时 ， 我 会 提醒 你 。 
你 可 能 经 常 需要 从 GitHub 上 下 载 修 正和 改进 后 的 源码 ， 更 新 本 地 仓库 。 完 成 这 个 操作 的 
命令 如 下 所 示 : 


$ git fetch --all 
$ git fetch --tags 
$ git reset --hard origin/master 


git fetch 命令 根据 GitHub 上 的 远程 仓库 更 新 本 地 仓库 的 提交 历史 和 标签 ， 但 不 会 真正 改动 
源 文件 ， 随 后 执行 的 git reset 命令 才 是 用 于 更 新 文件 的 操作 。 再 次 提醒 ， 执 行 git reset 








































































































注 1: 也 可 前 往 本 书 的 图 灵 社 区 页 面 (http:/www.ituring.com.cn/book/2463) 下 载 。 一 一 编者 注 

















命令 后 ， 本 地 修改 将 会 丢失 。 

另 一 个 有 用 的 操作 是 查看 应 用 两 个 版 本 之 间 的 差异 ， 以 便 了 解 改动 详情 。 在 命令 行 中 ， 可 以 使 
用 9it diff 命令 进行 查看 。 例 如 ， 执 行 下 述 命令 可 以 查看 2a 和 2b 两 个 修订 版 本 之 间 的 差异 : 

$ git diff 2a 2b 

这 个 命令 以 补丁 (patch) 的 形式 显示 差异 ， 如 果 你 以 前 没有 用 过 补丁 文件 ， 可 能 会 觉得 
这 种 查看 改动 的 方式 不 直观 。 你 可 能 发 现 ，GitHub 网 站 中 显示 的 图 形 化 对 比 更 容易 理 
解 。 例 如 ， 要 在 GitHub 中 查看 2a 和 2b 两 个 历史 版 本 的 差异 ， 可 以 访问 https://github.com/ 
miguelgrinberg/flasky/compare/2a...2b。 


使 用 代码 示例 


本 书 的 目的 是 帮助 你 完成 工作 。 一 般 来 说 ， 你 可 以 在 自己 的 程序 或 文档 中 使 用 本 书 附带 的 
示例 代码 。 你 无 须 联 系 我 们 获得 使 用 许可 ， 除 非 你 要 复制 大 量 的 代码 。 例 如 ， 使 用 本 书 中 
的 多 个 代码 片段 编写 程序 就 无 须 获 得 许可 。 但 以 CD-ROM 的 形式 销售 或 者 分 发 O'Reilly 
书 中 的 示例 代码 则 需要 获得 许可 。 回 答 问 题 时 援引 本 书 内 容 以 及 书 中 示例 代码 ， 无 须 获 得 
许可 。 在 你 自己 的 项 目 文档 中 使 用 本 书 大 量 的 示例 代码 时 ， 则 需要 获得 许可 。 

我 们 不 强制 要 求 署 名 ， 但 如 有 果 你 这 么 做 ， 我 们 次 表 感 激 。 署 名 一 般 包 括 书 名 、 作 者 、 出 
版 社 和 国际 标准 图 书 编号 。 例 如 : “Flask Web Development, 2nd Edition, by Miguel Grinberg 
(O’Reilly). Copyright 2018 Miguel Grinberg, 978-1-491-99173-2。” 

如 果 你 觉得 自身 情况 不 在 合理 使 用 或 上 述 人 允许 的 范围 内 ， 请 通过 邮件 和 我 们 联系 ， 地 址 是 


permissions@oreilly.com 。 


排版 约定 

本 书 使 用 下 述 排版 约定 。 

。 黑体 
表示 新 术语 。 

。 等 宽 字 体 (constant width) 
表示 命令 行 输出 和 程序 代码 请 单 ， 也 表示 正文 中 出 现 的 命 4 
数据 类 型 、 环 境 变量 、 语 名 和 关键 字 等 。 

。 加 粗 等 宽 字体 (constant width) 
表示 应 该 由 用 户 输 入 的 命令 或 其 他 文本 。 

。 和 斜体 等 宽 字体 (constant width) 或 放 在 尖 括 号 中 的 文本 
表示 需要 使 用 用 户 的 输入 值 代替 的 文本 ， 或 者 由 上 下 文 决 定 的 值 。 
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这 个 图 标 表 示 提 示 或 建议 。 








这 个 图 标 表 示 一 般 性 说 明 。 
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标 表 示警 告 或 提醒 。 











O'Reilly Safari 


。” Safari (前 身 为 Safari Books Online) 是 会 员 制 平台 ， 为 企业 、 政 
| Safa 门 | 府 、 教 学 人 员 和 个 人 提供 培训 和 参考 资料 。 

会 员 可 以 访问 上 千 种 图 书 、 培 训 视 频 、 学 习 路 径 、 交 互 式 教程 和 

精 选 播放 列表 。 这 些 资 源 由 250 多 家 出 版 社 提供 ， 包 括 O’Reilly Media、Harvard Business 


Review、Prentice Hall Professional、Addison-Wesley Professional、 Microsoft Press、Sams.、 

















Que、 Peachpit Press、 Adobe、 Focal Press、 Cisco Press、 John Wiley & Sons、 Syngress、 
Morgan Kaufmann、 IBM Redbooks、 Packt、 Adobe Press、 FT Press、Apress、Manning.、 
New Riders、McGraw-Hill、Jones & Bartlett 和 Course Technology， 等 等 。 


详情 请 访问 http://oreilly.com/safari。 
A 外 名 
联系 我 们 
请 把 对 本 书 的 意见 和 疑问 发 送 给 出 版 社 。 
美国 : 
O’Reilly Media, Inc. 


1005 Gravenstein Highway North 
Sebastopol, CA 95472 


中 国 : 

北京 市 西城 区 西直门 南大 街 2 号 成 铬 大 厦 C 座 807 室 (100035) 

奥 莱 利 技术 咨询 (北京 ) 有 限 公 司 
O’Reilly 的 每 一 本 书 都 有 专属 网 页 ， 你 可 以 在 那儿 找到 本 书 的 相关 信息 ， 包 括 勘 误 表 、 示 例 
代码 以 及 其 他 信息 *。 本 书 的 网 站 地 址 是 : http://shop.oreilly.com/product/0636920089056.do。 
如 果 你 对 本 书 有 一 些 建议 或 技术 上 的 疑问 ， 请 发 送 电 子 邮 件 至 bookquestions@oreilly.com。 
要 了 解 更 多 O’Reilly 图 书 、 培 训 课 程 、 会 议和 新 闻 的 信息 ， 请 访问 以 下 网 站 : http:/www. 
oreilly.com 。 
我 们 在 Facebook 的 地 址 如 下 : http://facebook.com/oreilly。 
请 关注 我 们 的 Twitter 动态 : http://twitter.com/oreillymedia。 
























































注 2: 中 文 版 勘误 请 前 往 本 书 的 图 灵 社 区 页 面 (http://www.ituring.com.cn/book/2463) 提交 。 一 一 编者 注 
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到 | 


我 们 的 YouTube 视频 地 址 如 下 : http:Wwww.youtube.comyoreillymedia。 


致谢 

仅 赁 我 一 个 人 是 无 法 完成 这 本 书 的 。 家 人 、 同 事 、 老 友 ， 以 及 写 书 过 程 中 认识 的 新 朋友 都 
给 了 我 很 大 的 帮助 。 

我 要 感谢 Brendan Kohler， 他 对 本 书 做 了 详尽 的 技术 审 校 ， 并 针对 第 14 章 提 供 了 宝贵 的 建 
议 。 还 要 感谢 David Baumgold、Todd Brunhoff、Cecil Rock 和 Matthew Hugues， 他 们 在 本 
书 撰写 的 不 同 阶 段 审阅 了 书稿 ， 并 对 涵盖 哪些 内 容 和 章节 规划 给 予 了 建设 性 建议 。 

本 书 示 例 代码 的 编写 花费 了 我 大 量 精力 。 我 很 感激 Daniel Hofmann 的 帮助 ， 他 对 这 个 
应 用 做 了 彻底 的 代码 审查 ， 并 指出 了 很 多 可 改进 之 处 。 还 要 感谢 我 十 几 岁 的 儿子 Dylan 
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测试 这 些 代码 。 

O’Reilly 有 个 极 好 的 项 目 ， 名 为 Early Release (提早 发 布 )， 可 以 让 迫不及待 的 读者 在 图 
书 撰写 过 程 中 就 进行 阅读 。 一 些 抢先 阅读 的 读者 不 仅 阅读 了 本 书 ， 还 加 入 了 讨论 ， 分 享 了 
他 们 阅读 本 书 的 体验 ， 这 为 本 书 的 改进 做 出 了 极 大 贡献 。 在 这 些 读者 中 ， 我 要 特别 感谢 
Sundeep Gupta、Dan Caron、Brian Wisti 和 Cody Scott 对 本 书 所 做 的 贡献 。 

O'Reilly Media 的 工作 人 员 始 终 陪 伴 着 我 。 首 先 我 要 特别 感谢 本 书 的 编辑 Meghan Blanchette， 
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第 一 部 分 





Flask 简 介 


第 1 
安 





泣 攻 


在 大 多 数 标准 中 ，EFlask 都 算是 小 型 框架 ， 小 到 可 以 称 为 “ 微 框架 *。Flask 非常 小 ， 因 此 你 
一 旦 能 够 熟练 使 用 它 ， 很 可 能 就 能 读 懂 它 所 有 的 源码 。 

但 是 ， 小 并 不 意味 着 它 比 其 他 框架 的 功能 少 。Flask 自 开发 伊始 就 被 设计 为 可 扩展 的 框架 ， 
它 具 有 一 个 包含 基本 服务 的 强健 核心 ， 其 他 功能 则 可 通过 扩展 实现 。 你 可 以 自己 挑选 所 需 
的 扩展 包 ， 组 成 一 个 没有 附加 功能 的 精益 组 合 ， 完 全 满足 自身 需求 。 

Flask 有 3 个 主要 依赖 路由、 调试 和 Web 服务 器 网 关 接 口 (WSGI,，Web server gateway 
interface) 子 系 统 由 Werkzeug 提供 ;模板 系统 由 Jinja2 提供 ; 命令 行 集成 由 Click 提供 。 
这 些 依赖 全 都 是 Flask 的 开发 者 Armin Ronacher 开发 的 。 


Flask 原生 不 支持 数据 库 访 问 、Web 表单 验证 和 用 户 身份 验证 等 高 级 功能 。 这 些 功能 以 及 
其 他 大 多 数 Web 应 用 需要 的 核心 服务 都 以 扩展 的 形式 实现 ， 然 后 再 与 核心 包 集成 。 开 发 者 
可 以 任意 挑选 符合 项 目 需求 的 扩展 ， 其 至 可 以 自行 开发 。 这 和 大 型 框架 的 做 法 相反 ， 大 型 
框架 往往 已 经 替 你 做 出 了 大 多 数 决 定 ， 难 以 (有 时 其 至 不 允许 ) 使 用 替代 方案 。 


本 章 介绍 如 何 安装 Flask。 在 这 个 过 程 中 ， 你 只 需要 一 台 安 装 了 Python 的 计算 机 。 
本 书 中 的 代码 示例 已 在 Python 3.5 和 Python 3.6 中 测试 过 。 如 果 你 愿意 ， 也 


可 以 使 用 Python 2.7。 不 过 这 一 版 将 在 2020 年 后 停止 维护 ， 因 此 强烈 建议 你 
使 用 3.x 版 。 



























































如 果 你 决定 使 用 运行 微软 Windows 系统 的 计算 机 ， 那 么 要 做 个 选择 : 要 么 使 
用 基于 Windows 的 “原生 ”工具 集 ， 要 么 设置 计算 机 ， 沿 用 基于 Unix 的 主 
流 工 具 集 。 本 书 中 的 代码 基本 上 在 两 种 方式 下 都 能 正常 运行 。 偶 有 差异 时 ， 
本 书 采 用 Unix 方式 ， 不 过 也 会 给 出 针对 Windows 的 说 明 。 

如 果 你 决定 采用 Unix 工作 流程 ， 有 几 个 选择 。 如 果 你 使 用 的 是 Windows 10， 
可 以 启用 WSL (Windows subsystem for Linux)。 这 是 官方 支持 的 功能 ， 在 
Windows 原生 界面 中 独立 运行 Ubuntu Linux。 通 过 WSL 可 以 访问 bash shell 
和 基于 Unix 的 全 套 工 具 集 。 如 果 你 的 系统 不 支持 WSL，Cygwin 也 是 不 错 
的 选择 。 这 是 一 个 开源 项 目 ， 模 仿 Unix 的 POSIX 子 系统 ， 而 且 移 植 了 大 量 
Unix 工具 。 




































































1.1 创建 应 用 目录 


首先 ， 要 新 建 一 个 目录 ， 存 放 从 GitHub 仓库 中 下 载 的 示例 代码 。 前 言 的 “如 何 使 用 示例 
代码 ”部 分 已 经 说 过 ， 最 简单 的 方法 是 使 用 Git 客户 端 直接 从 GitHub 仓库 中 拉 取 代码 。 下 
述 命 令 从 GitHub 中 下 载 示 例 代码 ， 并 检 出 应 用 的 1a 版 本 。 我 们 将 从 这 一 版 开始 。 

$ git clone https://github.com/miguelgrinberg/flasky.git 


$ cd flasky 
$ git checkout 1a 


如 果 你 不 想 使 用 Git， 打 算 自 己 动手 输入 或 复制 代码 ， 像 下 面 这 样 新 建 一 个 空 应 用 目录 即 可 : 


$ mkdir fLasky 
$ cd flasky 


1.2 ”虚拟 环境 


创建 好 应 用 目录 之 后 ， 接 下 来 该 安装 Flask 了 。 安 装 Flask 最 便捷 的 方法 是 使 用 虚拟 环境 。 
虚拟 环境 是 Python 解释 器 的 一 个 私有 副本 ， 在 这 个 环境 中 你 可 以 安装 私有 包 ， 而 且 不 会 影 
响 系统 中 安装 的 全 局 Python 解释 器 。 

虚拟 环境 非常 有 用 ， 可 以 避免 你 安装 的 Python 版 本 和 包 与 系统 预 装 的 发 生 冲 突 。 为 每 个 项 
目 单独 创建 虚拟 环境 ， 可 以 保证 应 用 只 能 访问 所 在 虚拟 环境 中 的 包 ， 从 而 保持 全 局 解释 器 
的 干净 整洁 ， 使 其 只 作为 创建 更 多 虚拟 环境 的 源 。 与 直接 使 用 系统 全 局 的 Python 解释 器 相 
比 ， 使 用 虚拟 环境 还 有 个 好 处 ， 那 就 是 不 需要 管理 员 权 限 。 


1.3 在 Python 3 中 创建 虚拟 环境 


Python 3 和 Python 2 解释 器 创建 虚拟 环境 的 方法 有 所 不 同 。 在 Python 3 中 ， 虚 拟 环境 由 
Python 标准 库 中 的 venv 包 原 生 支 持 。 
































如 果 你 使 用 的 是 Ubuntu Linux 系统 预 装 的 Python 3， 那 么 标准 库 中 没有 venv 
包 。 请 执行 下 述 命令 安装 python3-venv 包 : 


$ sudo apt-get instaLL python3-venv 








创建 虚拟 环境 的 命令 格式 如 下 : 

$ python3 -m venv virtual-environment-name 
-m venv 选项 的 作用 是 以 独立 的 脚本 运行 标准 库 中 的 venv 包 ， 后 面 的 参数 为 虚拟 环境 的 
名 称 。 
下 面 我 们 在 flasky 目录 中 创建 一 个 虚拟 环境 。 通常， 虚拟 环境 的 名 称 为 venv， 不 过 你 也 可 
以 使 用 其 他 名 称 。 确 保 当 前 目录 是 flasky， 然 后 执行 这 个 命令 : 

$ python3 -m venv venv 
这 个 命令 执行 完毕 后 ，flasky 目录 中 会 出 现 一 个 名 为 venv 的 子 目 录 ， 这 里 就 是 一 个 全 新 的 
虚拟 环境 ， 包 含 这 个 项 目 专用 的 Python 解释 器 。 


1.4 在 Python 2 中 创建 虚拟 环境 
Python 2 没有 集成 venv 包 。 这 一 版 Python 解释 器 要 使 用 第 三 方 工 具 virtualenv 创建 虚 
拟 环境 。 
确保 当前 目录 是 flasky， 然 后 根据 自己 使 用 的 操作 系统 ， 执 行 下 面 两 个 命令 中 的 一 个 。 如 
果 使 用 的 是 Linux 或 macOS ， 执 行 的 命令 是 ; 

$ sudo pip install virtualenv 
如 果 使 用 的 是 微软 Windows 系统 ， 打 开 命 令 提 示 符 时 要 选择 “以 管理 员 身 份 运行 "， 然 后 
执行 这 个 命令 : 

$ pip install virtualenv 
virtuatenv 命令 的 参数 是 虚拟 环境 的 名 称 。 确 保 当前 目录 是 flasky， 然 后 执行 下 述 命令 创 
建 名 为 venv 的 虚拟 环境 : 


$ virtualenv venv 

New python executable in venv/bin/python2.7 
Also creating executable in venv/bin/python 
Installing setuptools, pip, wheel...done. 


这 个 命令 在 当前 目录 中 创建 一 个 名 为 venv 的 子 目录 ， 虚 拟 环 境 相关 的 文件 都 在 这 个 子 目 录 中 。 


1.5 ”使 用 虚拟 环境 


若 想 使 用 虚拟 环境 ， 要 先 将 其 “激活 ”。 如 果 你 使 用 的 是 Linux 或 macOS， 可 以 通过 下 正 
的 命令 激活 虚拟 环境 : 


$ source venv/bin/activate 
















































































如 果 使 用 微软 Windows 系统 ， 激 活命 令 是 : 
$ venv\Scripts\activate 
虚拟 环境 被 激活 后 ， 里 面 的 Python 解释 器 的 路 径 会 添加 到 当前 命令 会 话 的 PATH 环境 变量 
中 ， 指 明 在 什么 位 置 寻找 一 众 可 执行 文件 。 为 了 提醒 你 已 经 激活 了 虚拟 环境 ， 激活 虚拟 环 
谤 的 命令 会 修改 命令 提示 符 ， 加 入 环境 名 : 
(venv) $ 
激活 虚拟 环境 后 ， 在 命令 提示 符 中 输入 python， 将 调用 虚拟 环境 中 的 解释 器 ， 而 不 是 系统 
全 局 解释 器 。 如 果 你 打开 了 多 个 命令 提示 符 窗口 ， 在 每 个 窗口 中 都 要 激活 虚拟 环境 。 
虽然 多 数 情况 下 ， 为 了 方便 ， 应 该 激活 虚拟 环境 ， 但 是 不 激活 也 能 使 用 虚 
拟 环境 。 例 如 ， 为 了 启动 venv 虚拟 环境 中 的 Python 控制 台 ， 在 Linux 或 


macOS 中 可 以 执行 venv/bin/python 命令 ， 在 微软 Windows 中 可 以 执行 
venv\Scripts\python 命令 。 



































虚拟 环境 中 的 工作 结束 后 ， 在 命令 提示 符 中 输入 deactivate， 还 原 当 前 终端 会 话 的 PATH 环 
境 变 量 ， 把 命令 提示 符 重 置 为 最 初 的 状态 。 


1.6 ”使 用 pip 安 装 Python 包 


Python 包 使 用 包 管理 器 pip 安装 ， 所 有 虚拟 环境 中 都 有 这 个 工具 。 与 python 命令 类 似 ， 在 
命令 提示 符 会 话 中 输入 pip 将 调用 当前 激活 的 虚拟 环境 中 的 pip 工具 。 
若 想 在 虚拟 环境 中 安装 Flask， 要 确保 venv 虚拟 环境 已 经 激活 ， 然 后 执行 下 述 命令 : 

(venv) $ pip install flask 


执行 这 个 命令 后 ，pip 不 仅 安装 Flask 自身 ， 还 会 安装 它 的 所 有 依赖 。 任 何 时 候 都 可 以 使 用 
pip freeze 命令 查看 虚拟 环境 中 安装 了 哪些 包 : 

(venv) $ pip freeze 

CLick==6.7 

FLask==0.12.2 

itsdangerous==0.24 

Jinja2==2.9.6 

MarkupSafe==1.0 

Werkzeug==0.12.2 


pip freeze 命令 的 输出 包含 各 个 包 的 具体 版 本 号 。 你 安装 的 版 本 号 可 能 与 这 里 给 出 的 不 同 。 
要 想 验 证 Flask 是 否 正确 安装 ， 可 以 局 动 Python 解释 器 ， 尝 试 导 入 Flask: 
(venv) $ python 


>>> import flask 
>>> 


如 果 没 有 看 到 错误 提醒 ， 那 么 恭喜 你 ， 你 可 以 开始 学 习 第 2 章 的 内 容 ， 了 解 如 何 编写 你 的 
第 一 个 Web 应 用 了 。 
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第 2 章 


应 用 的 基本 结构 





本 章 将 带领 你 了 解 Flask 应 用 各 部 分 的 作用 ， 编 写 并 运行 第 一 个 Flask Web 应 用 。 


2.1 初始 化 


所 有 Flask 应 用 都 必须 创建 一 个 应 用 实例 。Web 服务 器 使 用 一 种 名 为 Web 服务 器 网 关 接 口 
(WSGI，Web server gateway interface， 读 作 “wiz-ghee”) 的 协议 ， 把 接收 自 客户 端的 所 有 
请 求 都 转交 给 这 个 对 象 处 理 。 应 用 实例 是 Flask 类 的 对 象 ， 通 常 由 下 述 代码 创建 : 
from flask import Flask 
app = Flask(__name_) 
FLask 类 的 构造 函数 只 有 一 个 必须 指定 的 参数 ， 即 应 用 主 模块 或 包 的 名 称 。 在 大 多 数 应 用 
中 ，Python 的 __name__ 变量 就 是 所 需 的 值 。 
传 给 Flask 应 用 构造 函数 的 __name__ 参数 可 能 会 让 Flask 开发 新 手心 生 困惑 。 
Flask 用 这 个 参数 确定 应 用 的 位 置 ， 进 而 找到 应 用 中 其 他 文件 的 位 置 ， 例 如 
图 像 和 模板 。 






































后 文 会 介绍 更 复杂 的 应 用 初始 化 方式 ， 不 过 对 简单 的 应 用 来 说 ， 上 面 的 代码 足够 了 。 


2.2 ”路 由 和 视图 函数 


客户 端 (例如 Web 浏览 器 ) 把 请 求 发 送 给 Web 服务 器 ，Web 服务 器 再 把 请 求 发 送 给 Flask 
应 用 实例 。 应 用 实例 需要 知道 对 每 个 URL 的 请 求 要 运行 哪些 代码 ， 所 以 保存 了 一 个 URL 














到 Python 函数 的 映射 关系 。 处 理 URL 和 函数 之 间 关 系 的 程序 称 为 路 由 。 
在 Flask 应 用 中 定义 路 由 的 最 简便 方式 ， 是 使 用 应 用 实例 提供 的 app.route 装饰 器 。 下 面 
的 例子 说 明了 如 何 使 用 这 个 装饰 器 声明 路 由 : 

@app.route('/') 


def index(): 
return '<hi>Hello NorLd!</h1>' 








装饰 器 是 Python 语言 的 标准 特性 。 惯 常用 法 是 把 函数 注册 为 事件 处 理 程序 ， 
在 特定 事件 发 生 时 调用 。 























前 例 把 index() 函数 注册 为 应 用 根 地 址 的 处 理 程序 。 使 用 app.route 装饰 器 注册 视图 函 
数 是 首选 方法 ， 但 不 是 唯一 的 方法 。Flask 还 支持 一 种 更 传统 的 方式 : 使 用 app.add_url_ 
rule() 方法 。 这 个 方法 最 简单 的 形式 接受 3 个 参数 : URL、 端 点 名 和 视图 函数 。 下 述 示例 
使 用 app.add_url_rule() 方法 注册 index() 函数 ， 其 作用 与 前 例 相同 : 


def index(): 
return '<hi>Hello NorLd!</h1>' 








app.add_url_rule('/', 'index', index) 


index() 这 样 处 理 入 站 请 求 的 函数 称 为 视图 函数 。 如 果 应 用 部 署 在 域名 为 www.example. 
com 的 服务 器 上 ， 在 浏览 器 中 访问 http://www.example.com 后 ， 会 触发 服务 器 执行 index() 
函数 。 这 个 函数 的 返回 值 称 为 响应 ， 是 客户 端 接收 到 的 内 容 。 如 果 客 户 端 是 Web 浏览 器 ， 
响应 就 是 显示 给 用 户 查看 的 文档 。 视 图 函数 返回 的 响应 可 以 是 包含 HTML 的 简单 字符 串 ， 
也 可 以 是 后 文 将 介绍 的 复杂 表单 。 

直接 在 Python 源码 文件 中 编写 响应 字符 串 的 HTML 代码 会 导致 代码 难以 维 

护 ， 本 章 的 示例 这 么 做 只 是 为 了 介绍 响应 这 个 概念 。 你 将 在 第 3 章 了 解 生 成 

响应 更 好 的 方法 。 





























如 果 仔 细 观 察 日 常 所 用 服务 的 某 些 URL， 你 会 发 现 很 多 地 址 中 都 包含 可 变 部 分 。 例 如 ， 
你 的 Facebook 资料 页 面 的 地 址 是 http://www.facebook.com/<your-name>， 用 户 名 (your- 
name) 是 地 址 的 一 部 分 。Flask 支持 这 种 形式 的 URL， 只 需 在 app.route 装饰 器 中 使 用 特殊 
的 句法 即 可 。 下 例 定义 的 路 由 中 就 有 一 部 分 是 可 变 的 : 

@app.route('/user/<name>') 


def user(name): 
return '<hi>Hello, {}!</h1i>'.format(name) 


路 由 URL 中 放 在 尖 括 号 里 的 内 容 就 是 动态 部 分 ， 任 何 能 匹配 静态 部 分 的 URL 都 会 映射 到 
这 个 路 由 上 。 调 用 视图 函数 时 ，Flask 会 将 动态 部 分 作为 参数 传 入 函数 。 在 这 个 视图 函数 
中 ，name 参数 用 于 生成 个 性 化 的 欢迎 消息 。 














路 由 中 的 动态 部 分 默认 使 用 字符 串 ， 不 过 也 可 以 是 其 他 类 型 。 例 如 ， 路 由 /user/<int:id> 
只 会 匹配 动态 片段 id 为 整数 的 URL， 例 如 /user/123。Flask 支持 在 路 由 中 使 用 string、 
int、float 和 path 类 型 。path 类 型 是 一 种 特殊 的 字符 串 ， 与 string 类 型 不 同 的 是 ， 它 可 
以 包含 正 斜 线 。 


2.3 ”一 个 完整 的 应 用 
前 儿 节 介绍 了 Flask Web 应 用 的 不 同 组 成 部 分 ， 现 在 是 时 候 编写 第 一 个 应 用 了 。 如 前 所 述 ， 
示例 2-1 中 的 hello.py 应 用 脚本 定义 一 个 应 用 实例 、 一 个 路 由 和 一 个 视图 函数 。 


示例 2-1 hello.py: 一 个 完整 的 Flask 应 用 


from flask import Flask 
app = Flask(__name_ ) 








@app.route('/') 
def index(): 
return '<hi>Hello NorLd!</h1>' 





如 果 你 已 经 从 GitHub 上 克隆 了 这 个 应 用 的 Git 仓库 ， 那 么 可 以 执行 git 
checkout 2a 检 出 应 用 的 这 个 版 本 。 





2.4 ”Web 开发 服务 器 


Flask 应 用 自 带 Web 开发 服务 器 ， 通 过 fLask run 命令 启动 。 这 个 命令 在 FLASK_APP 环境 变 
量 指定 的 Python 脚本 中 寻找 应 用 实例 。 


车 想 启 动 前 一 节 编 写 的 hello.py 应 用 ， 首 先 确 保 之 前 创建 的 虚拟 环境 已 经 激活 ， 而 且 里 面 
安装 了 Flask。Linux 和 macOS 用 户 执 行 下 述 命令 启动 Web 服务 器 : 

(venv) $ export FLASK_APP=heLLo.py 

(venv) $ flask run 


* Serving FLask app "hello" 
* Running on http://127.0.0.1:5000/ (Press CTRL+C to quit) 


微软 Windows 用 户 执 行 的 命令 和 刚才 一 样 ， 只 不 过 设 定 FLASK_APP 环境 变量 的 方式 不 同 : 


(venv) $ set FLASK_APP=hello.py 

(venv) $ flask run 

* Serving Flask app "hello" 

* Running on http://127.0.0.1:5000/ (Press CTRL+C to quit) 


服务 器 启动 后 便 开始 轮 询 ， 处 理 请 求 。 直 到 按 Ctrl+C 键 停止 服务 器 ， 轮 询 才 会 停止 。 


服务 器 运行 时 ， 在 Web 浏览 器 的 地 址 栏 中 输入 http://Locathost:5000/。 你 看 到 的 页 面 如 
图 2-1 所 示 。 
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@ @ localhost:5000 


CO © localhost:5000 
Hello World! 














2-1: hello.py Flask 应 用 























如 果 在 基 URL 后 面 再 输入 任何 内 容 ， 应 用 将 不 知道 如 何 处 理 ， 会 向 浏览 器 返回 错误 码 
404。 这 个 错误 你 应 该 很 熟悉 ， 当 你 访问 不 存在 的 网 页 时 就 会 见 到 。 





Flask 提供 的 Web 服务 器 只 适用 于 开发 和 测试 。 第 


Flask Web 开发 服务 器 也 可 以 通过 编程 的 方式 启动 : 




















17 章 将 介绍 Web 生产 服 


调用 app.run() 方法 。 在 


没有 flask 命令 的 旧版 Flask 中 ， 若 想 启 动 应 用 ， 要 运行 应 用 的 主 脚 本 。 主 


脚本 的 尾部 包含 下 述 代码 片 段 : 


if _ name _ == '__main _': 
app.run() 











现在 有 了 flask run 命令 ， 我 们 就 无 须 再 这 么 做 了 。 
然 有 其 用 处 ， 例 如 在 单元 测试 中 (参见 第 15 章 )。 


2.5 动态 路 由 








不 过 ，app.run() 方法 依 


这 个 应 用 的 第 2 版 将 添加 一 个 动态 路 由 ， 如 示例 2-2 所 示 。 在 浏览 器 中 访问 这 个 动态 URL 
时 ， 你 会 看 到 一 条 个 性 化 的 消息 ， 包 含 你 在 URL 中 提供 的 名 字 。 


示例 2-2 hello.py: 包含 动态 路 由 的 Flask 应 用 
from flask import Flask 
app = Flask(__name__) 


@app.route('/') 
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def index(): 
return "<h1>HeLLo WorLd!</h1>' 


@app.route('/user/<name>') 
def user(name): 
return '<hi>Hello, {}!</hi>'.format(name) 


如 果 你 已 经 从 GitHub 上 克隆 了 这 个 应 用 的 Git 仓库， 那么 可 以 执行 git 
checkout 2b 检 出 应 用 的 这 个 版 本 。 








测试 动态 路 由 前 ， 请 确保 服务 器 正在 运行 中 ， 然 后 访问 http://localhost:5000/user/Dave。 应 
会 显示 一 个 使 用 name 动态 参数 生成 的 欢迎 消息 。 试 着 在 URL 中 设 定 不 同 的 名 字 ， 可 以 
看 到 ， 视 图 函数 总 是 使 用 指定 的 名 字 生 成 响应 。 图 2-2 展示 了 一 个 示例 。 

















@ @ localhost:5000/user/Dave 


一 GE 合 @Iocalhost 
Hello, Dave! 














图 2-2: 动态 路 由 


2.6 ”调试 模式 


Flask 应 用 可 以 在 调试 模式 中 运行 。 在 这 个 模式 下 ， 开 发 服务 器 默认 会 加 载 两 个 便利 的 工 
其 : 重 载 器 和 调试 器 。 

启用 重 载 器 后 ，Flask 会 监视 项 目 中 的 所 有 源码 文件 ， 发 现 变 动 时 自动 重启 服务 器 。 在 开 
发 过 程 中 运行 启动 重 载 器 的 服务 器 特别 方便 ， 因 为 每 次 修改 并 保存 源码 文件 后 ， 服 务 器 都 
会 自动 重启 ， 让 改动 生效 。 

调试 器 是 一 个 基于 Web 的 工具 ， 当 应 用 抛 出 未 处 理 的 异常 时 ， 它 会 出 现在 浏览 器 中 。 此 
时 ，Web 浏览 器 变 成 一 个 交互 式 栈 跟踪 ， 你 可 以 在 里 面 审查 源码 ， 在 调用 栈 的 任何 位 置 计 
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算 表 达 式 。 调 试 器 的 界面 如 图 2-3 所 示 。 





@ @ [ZeroDivisionError: division by x 


€ (Gi 合 @Iiocalhost 
builtins.ZeroDivisionError 


ZeroDivisionError: division by zero 








Traceback (most recent call last) 


File "/Users/miguel/flasky/venv/lib/python3.6/site-packages /flask/app.py", line 
1997,in__call__ 


return self.wsgi_app(Cenviron, start_response) 


File "/Users/miguel/flasky/venv/lib/python3.6/site-packages /flask/app.py", line 
1985, in wsgi_app 


response = self.handle_exception(e) 


File "/Users/miguel/flasky/venv/lib/python3.6/site-packages /flask/app.py", line 
1540, in handle_exception 


reraise(exc_type, exc_value, tb) 


File "/Users/miguel/flasky/venv/lib/python3.6/site-packages /flask/_compat.py”, 
line 33, in reraise 


raise value 








File "/Users/miguel/flasky/venv/lib/python3.6/site-packages /flask /app.py", line 
1982, in wsgi_app 











2-3，Flask 的 调试 器 





调试 模式 默认 禁用 。 若 想 启用 ， 在 执行 flask run 命令 之 前 设 定 FLASK_DEBUG=1 环境 变量 : 


(venv) $ export FLASK_APP=hello.py 

(venv) $ export FLASK_DEBUG=1 

(venv) $ flask run 

* Serving Flask app "hello" 

Forcing debug mode on 

Running on http://127.0.0.1:5000/ (Press CTRL+C to quit) 
Restarting with stat 

Debugger is active! 

Debugger PIN: 273-181-528 


在 微软 Windows 中 ， 环 境 变 量 使 用 set 设置 。 


汪汪 第 党 省 


使 用 app.run() 方法 启动 服务 器 时 ， 不 会 用 到 FLASK_APP 和 FLASK_DEBUG 环境 
变量 。 若 想 以 编程 的 方式 启动 调试 模式 ， 就 使 用 app.run(debug=True)。 








千 万 不 要 在 生产 服务 器 中 启用 调试 模式 。 客 户 端 通过 调试 器 能 请 求 执行 远 
程 代码 ， 因 此 可 能 导致 生产 服务 器 遭 到 攻击 。 作 为 一 种 简单 的 保护 措施 ， 
启动 调试 模式 时 可 以 要 求 输入 PIN 码 ， 执 行 flask run 命令 时 会 打印 在 控制 


人 
jm 


























2.7 命令 行 选项 


flask 命令 支持 一 些 选 项 。 执 行 flask --heLp， 或 者 执行 flask 而 不 提供 任何 参数 ， 可 以 
查看 哪些 选项 可 用 : 


(venv) $ flask --help 
Usage: flask [OPTIONS] COMMAND [ARGS]... 














This shell command acts as general utility script for Flask applications. 


It loads the application configured (through the FLASK_APP environment 
variable) and then provides commands either provided by the application or 
Flask itself. 


The most UsefuL commands are the "run" and "shell" command . 
Example usage: 


$ export FLASK_APP=hello.py 
$ export FLASK_DEBUG=1 
$ flask run 


Options: 
--version Show the flask version 
--help Show this message and exit. 


Commands: 
run Runs a development server. 
sheLL Runs a shell in the app context. 


flask shell 命令 在 应 用 的 上 下 文中 打开 一 个 Python shell 会 话 。 在 这 个 会 话 中 可 以 运行 维 
护 任务 或 测试 ， 也 可 以 调试 问题 。 几 章 之 后 将 举例 说 明 这 个 命令 的 用 途 

flask run 命令 我 们 已 经 用 过 ， 从 名 称 可 以 看 出 ， 它 的 作用 是 在 Web 开发 服务 器 中 运行 应 
用 。 这 个 命令 有 多 个 参数 : 


(venv) $ flask run --help 
Usage: flask run [OPTIONS] 





Runs a local development server for the FLask application. 


This local server is recommended for development purposes only but it can 
also be used for simple intranet deployments. By default it will not 
support any sort of concurrency at all to simplify debugging. This can be 
changed with the --with-threads option which will enable basic 
multithreading. 
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The reloader and debugger are by default enabled if the debug flag of 
Flask is enabled and disabled otherwise 


Options: 
-h, --host TEXT The interface to bind to. 
-p，--port INTEGER The port to bind to. 
--reload / --no-reload Enable or disable the reloader. By default 
the reloader is active if debug is enabled. 
--debugger / --no-debugger Enable or disable the debugger. By default 


the debugger is active if debug is enabled. 
--eager-loading / --lazy-loader 
Enable or disable eager loading. By default 
eager loading is enabled if the reloader is 
disabled. 
--with-threads / --without-threads 
Enable or disable multithreading. 
--help Show this message and exit. 


--host 参数 特别 有 用 ， 它 告诉 Web 服务 器 在 哪个 网 络 接口 上 监听 客户 端 发 来 的 连接 。 默 
认 情 况 下 ，Flask 的 Web 开发 服务 器 监听 localhost 上 的 连接 ， 因 此 服务 器 只 接受 运行 服务 
器 的 计算 机 发 送 的 连接 。 下 述 命令 让 Web 服务 器 监听 公共 网 络 接口 上 的 连接 ， 因 此 同一 网 
络 中 的 其 他 计算 机 发 送 的 连接 也 能 接收 到 ; 
(venv) $ flask run --host 0.0.0.0 


* Serving Flask app "hello" 
* Running on http://0.0.0.0:5000/ (Press CTRL+C to quit) 


现在 ， 网 络 中 的 任何 计算 机 都 能 通过 http://a.b.c.d:5000 访问 Web 服务 器 。 其 中 ，a.b.c.d 是 
运行 服务 器 sted 


--reload、--no-reload、--debugger 和 --no-debugger 参数 对 调试 模式 进行 细致 的 设置 。 
例如 ， 启 动 调试 模式 后 可 以 使 用 --no-debugger 关闭 调试 器 ， 但 是 应 用 还 在 调试 模式 中 运 
行 ， 而 且 重 载 器 也 启用 了 。 


2.8 请求- 响应 循环 


开发 了 一 个 简单 的 Flask 应 用 之 后 ， 你 或 许 希 望 进一步 了 解 Flask 的 工作 方式 。 下 面 几 节 将 
介绍 这 个 框架 的 一 些 设计 理念 


2.8.1 应 用 和 请 求 上 下 文 

Flask 从 客户 间 前 收 到 请 求 时 ， 要 让 视图 函 访问 一 些 对 象 ， 这 样 才 能 处 理 请 求 。 请 求 对 
象 就 是 一 个 很 好 的 例子 ， 它 封装 了 客户 端 发 送 的 HTTP 请 求 。 
要 想 让 视图 国 数 能 够 访问 请 求 对 象 ， 一 种 直截了当 的 方式 是 将 其 作为 参数 传人 视图 国 数 ， 
不 过 这 会 导致 应 用 中 的 每 个 视图 函数 都 多 出 一 个 参数 。 除 了 访问 请 求 对 象 ， 如 果 视 图 函数 
在 处 理 请 求 时 还 要 访问 其 他 对 象 ， 情 况 会 变 得 更 精 。 


为 了 避免 大 量 可 有 可 无 的 参数 把 视图 函数 弄 得 一 团 糟 ，Flask 使 用 上 下 文 临 时 把 某 些 对 象 


































































































变 为 全 局 可 访问 。 有 了 上 下 文 ， 便 可 以 像 下 面 这 样 编写 视图 函数 : 


from flask import request 





@app.route('/') 
def index(): 
User_agent = request.headers.get('User-Agent') 
return '<p>Your browser is {}</p>' .format(user_agent) 


注意 ， 在 这 个 视图 函数 中 我 们 把 request 当 作 全 局 变量 使 用 。 事 实 上 ，request 不 可 能 是 全 
局 变量 。 试 想 ， 在 多 线程 服务 器 中 ， 多 个 线程 同时 处 理 不 同 客户 端 发 送 的 不 同 请 求 时 ， 每 
个 线程 看 到 的 request 对 象 必然 不 同 。Flask 使 用 上 下 文 让 特定 的 变量 在 一 个 线程 中 全 局 可 
访问 ， 与 此 同时 却 不 会 干扰 其 他 线程 。 


线程 是 可 单独 管理 的 最 小 指令 集 。 进 程 经 常 使 用 多 个 活动 线程 ， 有 时 还 会 共 
享 内 存 或 文件 句柄 等 资源 。 多 线程 Web 服务 器 会 创建 一 个 线程 池 ， 再 从 线 
程 池 中 选择 一 个 线程 处 理 接收 到 的 请 求 。 


















































在 Flask 中 有 两 种 上 下 文 : 应 用 上 下 文 和 请 求 上 下 文 。 表 2-1 列 出 了 这 两 种 上 下 文 提供 的 


* 上肢- 
变量 。 


表 2-1: Flask 上 下 文 全 局 变量 

















变量 名 上 下 文 说 明 

current_app 应 用 上 下 文 当前 应 用 的 应 用 实例 

9 应 用 上 下 文 处 理 请 求 时 用 作 临 时 存储 的 对 象 ， 每 次 请 求 都 会 重 设 这 个 变量 
request 请 求 上 下 文 请 求 对 象 ， 封 装 了 客户 端 发 出 的 HTTP 请 求 中 的 内 容 

session 请 求 上 下 文 用 户 会 话 ， 值 为 一 个 字典 ， 存 储 请 求 之 间 需 要 “ 记 住 ”的 值 














Flask 在 分 派 请 求 之 前 激活 (或 推送 ) 应 用 和 请 求 上 下 文 ， 请 求 处 理 完成 后 再 将 其 删除 。 应 
用 上 下 文 被 推送 后 ， 就 可 以 在 当前 线程 中 使 用 current_app 和 9 变量 。 类 似 地 ， 请 求 上 下 
文 被 推送 后 ， 就 可 以 使 用 request 和 session 变量 。 如 果 使 用 这 些 变量 时 没有 激活 应 用 上 
下 文 或 请 求 上 下 文 ， 就 会 导致 错误 。 如 果 你 不 知道 为 什么 这 4 个 上 下 文 变量 如 此 有 用 ， 先 
别 担心 ， 本 章 及 后 面 的 章节 会 详细 说 明 。 


下 述 Python shell 会 话 演示 了 应 用 上 下 文 的 使 用 方法 : 


>>> from hello import app 

>>> from flask import current_app 
>>> current_app.name 

Traceback (most recent call last): 








RuntimeError: working outside of application context 
>>> app_ctx = app.app_context() 

>>> app_ctx.push() 

>>> CUrrent_app.name 

'hello' 


>>> app_ctx.pop() 


在 这 个 例子 中 ， 没 激活 应 用 上 下 文 之 前 就 调用 current_app.name 会 导致 错误 ， 但 推送 完 
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上 下 文 之 后 就 可 以 调用 了 。 注 意 ， 获 取 应 用 上 下 文 的 方法 是 在 应 用 实例 上 调用 app.app_ 


Context() 。 


2.8.2 ”请 求 分 派 

应 用 收 到 客户 端 发 来 的 请 求 时 ， 要 找到 处 理 该 请 求 的 视图 函数 。 为 了 完成 这 个 任务 ，Flask 
会 在 应 用 的 URL 映射 中 查找 请 求 的 URL。URL 映射 是 URL 和 视图 函数 之 间 的 对 应 关系 。 
Flask 使 用 app.route 装饰 器 或 者 作用 相同 的 app.add_url_rule() 方法 构建 映射 。 


要 想 查看 Flask 应 用 中 的 URL 映射 是 什么 样子 ， 可 以 在 Python shell 中 审查 为 hello.py 生成 
的 映射 。 测 试 之 前 ， 请 确保 你 激活 了 虚拟 环境 : 


(venv) $ python 

>>> from heLLo import app 

>>> app.urL_map 

Map([<Rule '/' (HEAD, OPTIONS, GET) -> index>, 

<Rule '/static/<filename>' (HEAD, OPTIONS, GET) -> static>, 
<Rule '/user/<name>' (HEAD, OPTIONS, GET) -> user>]) 

















/ 和 /user/<name> 路 由 在 应 用 中 使 用 app.route 装饰 器 定义 。/static/<filename> 路 由 是 
Flask 添加 的 特殊 路 由 ， 用 于 访问 静态 文件 。 第 3 章 将 详细 介绍 静态 文件 。 


URL 映射 中 的 (HEAD， 0PTIONS， GET) 是 请 求 方法 ， 由 路 由 进行 处 理 。HTTP 规范 中 规定 ， 
每 个 请 求 都 有 对 应 的 处 理 方法 ， 这 通常 表示 客户 端 想 让 服务 器 执行 什么 样 的 操作 。Flask 
为 每 个 路 由 都 指定 了 请 求 方法 ， 这 样 即使 不 同 的 请 求 方法 发 送 到 相同 的 URL 上 时 ， 也 会 
使 用 不 同 的 视图 函数 处 理 。HEAD 和 OPTIONS 方法 由 Flask 自动 处 理 ， 因 此 可 以 这 么 说 ,在 
这 个 应 用 中 ，URL 映射 中 的 3 个 路 由 都 使 用 GET 方法 (表示 客户 端 想 请 求 信息 ， 例 如 一 个 
网 页 )。 第 4 章 将 介绍 如 何 为 路 由 指定 不 同 的 请 求 方法 。 


2.8.3 ”请 求 对 象 

我 们 知道 ，Flask 通过 上 下 文 变量 request 对 外 开放 请 求 对 象 。 这 个 对 象 非常 有 用 ， 包 含 客 
户 端 发 送 的 HTTP 请 求 的 全 部 信息 。Flask 请 求 对 象 中 最 常用 的 属性 和 方法 见 表 2-2。 

表 2-2: Flask 请 求 对 象 














































































































属性 或 方法 说 明 

form 个 字典 ， 存 储 请 求 提交 的 所 有 表单 字段 

args 个 字典 ， 存 储 通过 URL 查询 字符 串 传递 的 所 有 参数 
values 个 字典 ，form 和 args 的 合集 

cookies 个 字典 ， 存 储 请 求 的 所 有 cookie 

headers 个 字典 ， 存 储 请 求 的 所 有 HTTP 首部 

files 个 字典 ， 存 储 请 求 上 传 的 所 有 文件 

get_data( ) 返回 请 求 主体 缓冲 的 数据 

get_json() 返回 一 个 Python 字典 ， 包 含 解析 请 求 主体 后 得 到 的 JSON 
blueprint 处 理 请 求 的 Flask 蓝本 的 名 称 ， 蓝 本 在 第 7 章 介绍 
















































































属性 或 方法 说 明 

endpoint 处 理 请 求 的 Flask 端点 的 名 称 ，Flask 把 视图 函数 的 名 称 用 作 路 由 端点 的 名 称 
method HTTP 请 求 方法 ， 例 如 GET 或 POST 

scheme URL 方案 (http 或 https) 

is_secure() 通过 安全 的 连接 (HTTPS) 发 送 请 求 时 返回 True 

host 请 求 定义 的 主机 名 ， 如 果 客 户 端 定义 了 端口 号 ， 还 包括 端口 号 
path URL 的 路 径 部 分 

query_string URL 的 查询 字符 串 部 分 ， 返 回 原始 二 进 制 值 

full_path URL 的 路 径 和 查询 字符 串 部 分 

url 客户 端 请 求 的 完整 URL 

base_url 同 urL， 但 没有 查询 字符 串 部 分 

remote_addr 客户 端的 全 地址 

environ 请 求 的 原始 WSGI 环境 字典 


2.8.4 请 求 钩子 
有 时 在 处 理 请 求 之 前 或 之 后 执行 代码 会 很 有 用 。 例 如 ， 在 请 求 开始 时 ， 我 们 可 能 需要 创 
建 数 据 库 连接 或 者 验证 发 起 请 求 的 用 户 身份 。 为 了 避免 在 每 个 视图 函数 中 都 重复 编写 代 
码 ，Flask 提供 了 注册 通用 函数 的 功能 ， 注 册 的 函数 可 在 请 求 被 分 派 到 视图 函数 之 前 或 之 
后 调用 。 
请 求 钧 子 通过 装饰 器 实现 。EFlask 支持 以 下 4 种 钧 子 。 
before_request 

注册 一 个 函数 ， 在 每 次 请 求 之 前 运行 。 
before first_ request 


注册 一 个 函数 ， 只 在 处 理 第 一 个 请 求 之 前 运行 。 可 以 通过 这 个 钧 子 添加 服务 器 初始 化 
任务 

















after_request 
注册 一 个 函数 ， 如 果 没 有 未 处 理 的 异常 抛 出 ， 在 每 次 请 求 之 后 运行 。 
teardown_request 
注册 一 个 国 数 ， 即 使 有 未 处 理 的 异常 抛 出 ， 也 在 每 次 请 求 之 后 运行 。 


在 请 求 钧 子 函 数 和 视图 函数 之 间 共 享 数据 一 般 使 用 上 下 文 全 局 变量 g。 例 如 ，before_ 
request 处 理 程序 可 以 从 数据 库 中 加 载 已 登录 用 户 ， 并 将 其 保存 到 g.user 中 。 随 后 调用 视 
图 函数 时 ， 便 可 以 通过 g.user 获取 用 户 。 


请 求 钩子 的 用 法 将 在 后 续 章 节 中 介绍 ， 如 果 你 现在 不 太 理解 ， 也 不 用 担心 。 
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2.8.5 响应 


Flask 调用 视图 函数 后 ， 会 将 其 返回 值 作为 响应 的 内 容 。 多 数 情况 下 ， 响 应 就 是 一 个 简单 
的 字符 种 ， 作 为 HTML 页 面 回 送 客 户 端 。 


但 HTTP 协议 需要 的 不 仅 是 作为 请 求 响应 的 字符 串 。HTTP 响应 中 一 个 很 重要 的 部 分 是 状 
态 码 ，Flask 默认 设 为 200， 表 明 请 求 已 被 成 功 处 理 


如 果 视 图 函数 返回 的 响应 需要 使 用 不 同 的 状态 码 ， 可 以 把 数字 代码 作为 第 二 个 返回 值 ， 添 
加 到 响应 文本 之 后 。 例 如 ， 下 述 视 图 函数 返回 400 状态 码 ， 表 示 请 求 无 效 : 
@app.route('/') 


def index(): 
return '<h1>Bad Request</h1>', 400 


视图 函数 返回 的 响应 还 可 接受 第 三 个 参数 ， 这 是 一 个 由 HITP 响应 首部 组 成 的 字典 。 第 14 
章 将 举例 说 明 如 何 自 定义 响应 首部 。 

如 果 不 想 返回 由 1 个 、 2 个 或 3 个 值 组 成 的 元 组 ，Flask 视图 函数 还 可 以 返回 一 个 响应 对 
象 。make_response() 函数 可 接受 1 个 、2 个 或 3 个 参数 (和 视图 函数 的 返回 值 一 样 )， 然 
后 返回 一 个 等 效 的 响应 对 象 。 有 了 时 我 们 需要 在 视图 函数 中 生成 响应 对 象 ， 然 后 在 响应 对 象 
上 调用 各 个 方法 ， 进 一 步 设置 响应 。 下 例 创建 一 个 响应 对 象 ， 然 后 设置 cookie: 


from flask import make_response 
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@app.route('/') 

def index(): 
response = make_response('<h1i>This document carries a cookie!</h1i>') 
response.set cookie('answer', '42') 
return response 


响应 对 象 最 常 使 用 的 属性 和 方法 见 表 2-3。 
表 2-3: Flask 响 应 对 象 




















属性 或 方法 说 明 

status_code HTTP 数字 状态 码 

headers 一 个 类 似 字典 的 对 象 ， 包 含 随 响应 发 送 的 所 有 首部 
set_cookie() 为 响应 添加 一 个 cookie 

detLete_cookie() 删除 一 个 cookie 

content_length 响应 主体 的 长 度 

content_type 响应 主体 的 媒体 类 型 

set_data() 使 用 字符 串 或 字 节 值 设 定 响应 

get_data() 获取 响应 主体 








响应 有 个 特殊 的 类 型 ， 称 为 重 定向 。 这 种 响应 没有 页 面 文档 ， 只 会 告诉 浏览 器 一 个 新 
URL， 用 以 加 载 新 页 面 。 重 定向 经 常 在 Web 表单 中 使 用 ， 第 4 章 会 介绍 。 

重 定向 的 状态 码 通常 是 302， 在 Location 首部 中 提供 目标 URL。 重 定向 响应 可 以 使 用 3 
个 值 形式 的 返回 值 生成 ， 也 可 在 响应 对 象 中 设 定 。 不 过 ， 由 于 使 用 频 紫 ，Flask 提供 了 
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redirect() 辅助 函数 ， 用 于 生成 这 种 响应 : 


from flask import redirect 


@app.route('/') 
def index(): 
return redirect('http://www.example.com') 
还 有 一 种 特殊 的 响应 由 abort() 函数 生成 ， 用 于 处 理 错 误 。 在 下 面 这 个 例子 中 ， 如 果 URL 
中 动态 参数 id 对 应 的 用 户 不 存在 ， 就 返回 状态 码 404: 


from flask import abort 





















































@app.route('/user/<id>') 
def get user(id): 
user = load user(id) 
if not user: 
abort(404) 
return '<hi>Hello, {}</h1i>'.format(user .name) 


注意 ，abort() 不 会 把 控制 权 交 还 给 调用 它 的 函数 ， 而 是 抛 出 异常 。 


2.9 Flask 扩 展 

Flask 的 设计 考虑 了 可 扩展 性 ， 故 而 没有 提供 一 些 重要 的 功能 ， 例 如 数据 库 和 用 户 身 份 验 
证 ， 所 以 开发 者 可 以 自由 选择 最 适合 应 用 的 包 ， 或 者 按 需 求 自 行 开 发 。 

社区 成 员 开 发 了 大 量 不 同 用 途 的 Flask 扩展 ， 如 果 这 还 不 能 满足 需求 ， 任 何 Python 标准 包 
或 代码 库 都 可 以 使 用 。 第 3 章 将 首次 用 到 Flask 扩展 。 


本 章 介 绍 了 请 求 响 应 的 概念 ， 不 过 响应 的 知识 还 有 很 多 。Flask 为 使 用 模板 生成 响应 提供 
了 良好 支持 ， 这 是 个 很 重要 的 话题 ， 下 一 章 会 专门 讨论 。 
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要 想 开发 出 易于 维护 的 应 用 ， 关 键 在 于 编写 形式 简洁 且 结 构 良 好 的 代码 。 目 前 为 止 ， 你 看 
到 的 示例 都 太 简单 ， 无 法 说 明 这 一 点 ， 但 Flask 视图 函数 的 两 个 完全 独立 的 作用 却 被 融合 
在 了 一 起 ， 这 就 产生 了 一 个 问题 。 

质 图 函数 的 作用 很 明确 起 即 生 成 请 汞 的 响 而 ， 如 第 2 章 中 的 示例 所 示 。 对 最 简单 的 请 求 
来 说 ， 这 就 足够 了 ， 但 很 多 情况 下 ， 请 求 会 改变 应 用 的 状态 ， 而 这 种 变化 就 发 生 在 视图 
函数 中 。 

以 用 户 在 网 站 中 注册 新 账户 的 过 程 为 例 。 用 户 在 表单 中 输入 电子 邮件 地 址 和 密码 ， 然 后 点 
击 提交 按钮 。 服 务 器 接收 到 包含 用 户 输入 数据 的 请 求 ， 然 后 Flask 把 请 求 分 派 给 处 理 注册 
请 求 的 视图 函数 。 这 个 视图 函数 需要 访问 数据 库 ， 添 加 新 用 户 ， 然 后 生成 响应 回 送 浏览 
器 ， 指 明 操 作成 功 还 是 失败 。 这 两 个 过 程 分 别称 为 业务 逻辑 和 表现 逻辑 。 

把 业务 逻辑 和 表现 逻辑 混在 一 起 会 导致 代码 难以 理解 和 维护 。 假 设 要 为 一 个 大 型 表格 构建 
HTML 代码 ， 表 格 中 的 数据 由 数据 库 中 读 取 的 数据 以 及 必要 的 HTML 字符 串 连 接 在 一 起 。 
把 表现 逻辑 移 到 模板 中 能 提升 应 用 的 可 维护 性 。 


模板 是 包含 响应 文本 的 文件 ， 其 中 包含 用 占 位 变量 表示 的 动态 部 分 ， 其 具体 值 只 在 请 求 的 
上 下 文中 才能 知道 。 使 用 真实 值 替 换 变量 ， 再 返回 最 终 得 到 的 响应 字符 串 ， 这 一 过 程 称 为 
泻 染 。 为 了 泻 染 模 板 ，Flask 使 用 一 个 名 为 Jinja2 的 强大 模板 引擎 。 


3.1 Jinja2 模 板 引擎 


形式 最 简单 的 Jinja2 模板 就 是 一 个 包含 响应 文本 的 文件 。 示 例 3-1 是 一 个 Jinja2 模板 ， 它 
和 示例 2-1 中 index() 视图 函数 的 响应 一 样 。 
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示例 3-1 templates/index.html: Jinja2 模板 
<hi>Hello NorLd!</h1> 


示例 2-2 中 ， 视 图 函数 user() 返回 的 响应 中 包含 一 个 使 用 变量 表示 的 动态 部 分 。 示 例 3-2 
使 用 模板 实现 了 这 个 响应 。 


示例 3-2 ”templates/user.html: Jinja2 模板 
<hi>Hello, {{ name }}!</h1> 


3.1.1” 泻 染 模 板 
默认 情况 下 ，Flask 在 应 用 目录 中 的 templates 子 目 录 里 寻找 模板 。 在 下 一 个 hello.py 版 本 


中 ， 你 要 新 建 ttmplates 子 目录 ， 再 把 前 面 定义 的 模板 保存 在 里 面 ， 分 别 命名 为 index.html 
和 user.html。 


应 用 中 的 视图 函数 需要 修改 一 下 ， 以 便 泻 染 这 些 模 板 。 修 改 方法 参见 示例 3-3。 
示例 3-3 hello.py: 演 染 模板 


from flask import Flask, render_template 























# 


@app.route('/') 
def index(): 
return render_template('index.html') 


@app.route('/user/<name>') 
def user(name): 
return render_template('user.html', name=name) 


Flask 提供 的 render_template() 函数 把 Jinja2 模板 引擎 集成 到 了 应 用 中 。 这 个 函数 的 第 一 
个 参数 是 模板 的 文件 名 ， 随 后 的 参数 都 是 键 - 值 对 ， 表 示 模 板 中 变量 对 应 的 具体 值 。 在 这 
段 代 码 中 ， 第 二 个 模板 收 到 一 个 名 为 name 的 变量 。 

前 例 中 的 name=name 是 经 常 使 用 的 关键 字 参 数 ， 如 果 你 不 熟悉 的 话 ， 可 能 不 知 所 云 。 左 边 
的 name 表示 参数 名 ， 就 是 模板 中 使 用 的 占 位 符 ， 右 边 的 name 是 当前 作用 域 中 的 变量 ， 表 
示 同 名 参数 的 值 。 两 侧 使 用 相同 的 变量 名 是 很 常见 ， 但 不 是 强制 要 求 。 











如 果 你 从 GitHub 上 克隆 了 这 个 应 用 的 Git 仓库 ， 那 么 可 以 执行 git checkout 
3a 检 出 应 用 的 这 个 版 本 。 

















3.1.2 ”变量 


示例 3-2 在 模板 中 使 用 的 {{ name 直 结构 表示 一 个 变量 ， 这 是 一 种 特殊 的 占 位 符 ， 告 诉 模 
板 引 擎 这 个 位 置 的 值 从 浑 染 模板 时 使 用 的 数据 中 获取 。 
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Jinja2 能 识别 所 有 类 型 的 变量 ， 其 至 是 一 些 复 杂 的 类 型 ， 例 如 列表 、 字 典 和 对 象 。 下 面 是 
在 模板 中 使 用 变量 的 一 些 示例 : 


<p>A value from a dictionary: {{ mydict['key'] }}.</p> 

<p>A value from a list: {{ mylist[3] }}.</p> 

<p>A value from a list, with a variable index: {{ mylist[myintvar] }}.</p> 
<p>A value from an object's method: {{ myobj.somemethod() }}.</p> 


变量 的 值 可 以 使 用 过 滤器 修改 。 过 滤器 添加 在 变量 名 之 后 ， 二 者 之 间 以 竖 线 分 隔 。 例 如 ， 
下 述 模板 把 name 变量 的 值 变 成 首 字母 大 写 的 形式 ， 
Hello, {{ name|capitalize }} 
表 3-1 列 出 了 Jinja2 提供 的 部 分 常用 过 滤器 。 
表 3-1: Jinja2 变 量 过 滤器 



































过 滤器 名 说 明 

safe 泻 染 值 时 不 转 义 

capitalize 把 值 的 首 字 母 转换 成 大 写 ， 其 他 字母 转换 成 小 写 
Lower 把 值 转换 成 小 写 形式 

upper 把 值 转换 成 大 写 形式 

title 把 值 中 每 个 单词 的 首 字母 都 转换 成 大 写 

trim 把 值 的 首尾 空格 删 掉 

striptags 泻 染 之 前 把 值 中 所 有 的 HTML 标签 都 删 掉 





safe 过 滤器 值得 特别 说 明 一 下 。 默 认 情 况 下 ， 出 于 安全 考虑 ，Jinja2 会 转 义 所 有 变量 。 例 
如 ， 如 果 一 个 变量 的 值 为 '<h1>Hello</h1>' ，Jinja2 会 将 其 演 染 成 '&Lt;h1l&gt;HeLLo&Lt;/ 
hi&gt;'， 浏 览 器 能 显示 这 个 hi 元素 ,但 不 会 解释 它 。 很 多 情况 下 需要 显示 变量 中 存储 的 
HTML 代码 ， 这 时 就 可 使 用 safe 过 滤器 。 






































千 万 别 在 不 可 信 的 值 上 使 用 safe 过 滤器 ， 例 如 用 户 在 表单 中 输入 的 文本 。 








完整 的 过 滤器 列表 可 在 Jinja2 文档 (http://jinja.pocoo.org/docs/2.10/templates/#builtin-filters) 
中 查看 。 


3.1.3 控制 结构 
Jinja2 提供 了 多 种 控制 结构 ， 可 用 来 改变 模板 的 谊 娄 流 程 。 本 节 通 过 简单 的 例子 介绍 其 中 
最 有 用 的 一 些 控制 结构 。 
下 面 这 个 例子 展示 如 何在 模板 中 使 用 条 件 判断 语句 : 
{% if user %} 


Hello, {{ user }}! 
{% else %} 
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Hello, Stranger! 
{% endif %} 


另 一 种 常见 需求 是 在 模板 中 谊 娄 一 组 元 素 。 下 例 展示 了 如 何 使 用 for 循环 实现 这 一 需求 : 


<UL> 
{% for comment in comments %} 
<li>{{ comment }}</li> 
{% endfor %} 
</ul> 


Jinja2 还 支持 宏 。 宏 类 似 于 Python 代码 中 的 函数 。 例 如 : 


{% macro render_comment(comment) %} 
<li>{{ comment }}</li> 
{% endmacro %} 





<ul> 
{% for comment in comments %} 
{{ render_comment(comment) }} 
{% endfor %} 
</ul> 


为 了 重复 使 用 宏 ， 可 以 把 宏 保 存在 单独 的 文件 中 ， 然 后 在 需要 使 用 的 模板 中 导入 : 


{% import 'macros.html' as macros %} 
<ul> 
{% for comment in comments %} 
{{ macros.render_comment(comment) }} 
{% endfor %} 
</ul> 


需要 在 多 处 重复 使 用 的 模板 代码 片段 可 以 写 入 单独 的 文件 ， 再 引入 所 有 模板 中 ， 以 避免 重复 : 


{% include 'common.html' %} 


另 一 种 重复 使 用 代码 的 强大 方式 是 模板 继承 ， 这 类 似 于 Python 代码 中 的 类 继承 。 首 先 ， 创 
建 一 个 名 为 base.html 的 基 模 板 : 


<html> 
<head> 
{% block head %} 
<title>{% block title %}{% endblock %} - My Application</title> 
{% endblock %} 
</head> 
<body> 
{% block body %} 
{% endblock %} 
</body> 
</html> 


基 模 板 中 定义 的 区 块 可 在 衍生 模板 中 覆盖 。Jinja2 使 用 block 和 endblock 指令 在 基 模 板 中 
定义 内 容 区 块 。 在 本 例 中 ， 我 们 定义 了 名 为 head、titte 和 body 的 区 块 。 注 意 ，title 包 
含 在 head 中 。 下 面 这 个 示例 是 基 模 板 的 衍生 模板 : 
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{% extends "base.html" %} 
{% block title %}Index{% endblock %} 
{% block head %} 
{{ super() }} 
<style> 
</style> 
{% endblock %} 
{% block body %} 
<hi>Hello, World!</h1i> 
{% endblock %} 


extends 指令 声明 这 个 模板 衍生 自 base.html。 在 extends 指令 之 后 ， 基 模板 中 的 3 个 区 块 
被 重新 定义 ， 模 板 引擎 会 将 其 插入 适当 的 位 置 。 如 果 基 模板 和 衍生 模板 中 的 同名 区 块 中 都 
有 内 容 ， 衍 生 模板 中 的 内 容 将 显示 出 来 。 在 衍生 模板 的 区 块 里 可 以 调用 super()， 引 用 基 
模板 中 同名 区 块 里 的 内 容 。 上 例 中 的 head 区 块 就 是 这 么 做 的 。 


稍 后 会 展示 这 些 控制 结构 的 具体 用 法 ， 让 你 了 解 一 下 它们 的 工作 原理 。 


3.2 ”使 用 Flask-Bootstrap 集 成 Bootstrap 


Bootstrap 是 Twitter 开发 的 一 个 开源 Web 框架 ， 它 提供 的 用 户 界 面 组 件 可 用 于 创建 整洁 且 
具有 吸引 力 的 网 页 ， 而 且 兼 容 所 有 现代 的 桌面 和 移动 平台 Web 六 览 器 。 

Bootstrap 是 客户 端 框架 ， 因 此 不 会 直接 涉及 服务 器 。 服 务 器 需要 做 的 只 是 提供 引用 了 
Bootstrap 层 秋 样式 表 (CSS，cascading style sheet) 和 JavaScript 文件 的 HTML 响应 ， 并 在 
HTML、CSS 和 JavaScript 代码 中 实例 化 所 需 的 用 户 界 面 元 素 。 这 些 操作 最 理想 的 执行 场 
所 就 是 模板 。 

要 想 在 应 用 中 集成 Bootstrap， 最 直接 的 方法 是 根据 Bootstrap 文档 中 的 说 明 对 HTML 模板 
进行 必要 的 改动 。 不 过 ， 这 个 任务 使 用 Flask 扩展 处 理 要 简单 得 多 ， 而 且 相 关 的 改动 不 会 
导致 主 逻 辑 凌 乱 不 堪 。 
我 们 要 使 用 的 扩展 是 Flask-Bootstrap ， 它 可 以 使 用 pip 安装 : 

(venv) $ pip install flask-bootstrap 


Flask 扩展 在 创建 应 用 实例 时 初始 化 。 示 例 3-4 是 Flask-Bootstrap 的 初始 化 方式 。 


示例 3-4 hello.py: 初始 化 Flask-Bootstrap 


from flask_bootstrap import Bootstrap 
Hd 
bootstrap = Bootstrap(app) 


扩展 通常 从 flask_<name> 包 中 导入 ， 其 中 <name> 是 扩展 的 名 称 。 多 数 Flask 扩展 采用 两 种 
初始 化 方式 中 的 一 种 。 在 示例 3-4 中 ， 初 始 化 扩展 的 方式 是 把 应 用 实例 作为 参数 传 给 构造 
函数 。 第 7 章 将 介绍 大 型 应 用 初始 化 扩展 的 一 种 高 级 方式 。 

初始 化 Flask-Bootstrap 之 后 ， 就 可 以 在 应 用 中 使 用 一 个 包含 所 有 Bootstrap 文件 和 一 般 结构 
的 基 模板 。 应 用 利用 Jinja2 的 模板 继承 机 制 来 扩展 这 个 基 模板 。 示 例 3-5 是 把 user.html 改 
写 为 衍生 模板 后 的 新 版 本 。 
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示例 3-5 templates/user.html: 使 用 Flask-Bootstrap 的 模板 
{% extends "bootstrap/base.html" %} 


{% block title %}Flasky{% endbLock %} 


{% block navbar %} 
<div class="navbar navbar-inverse" role="navigation"> 
<div class="container"> 
<div class="navbar-header"> 
<button type="button" class="navbar-toggle" 
data-toggle="collapse" data-target=".navbar-collapse"> 
<span class="sr-only">Toggle navigation</span> 
<span class="icon-bar"></span> 
<span class="icon-bar"></span> 
<span class="icon-bar"></span> 
</button> 
<a class="navbar-brand" href="/">Flasky</a> 
</div> 
<div class="navbar-collapse collapse'"> 
<ul class="nav navbar-nav "> 
<li><a href="/">Home</a></1li> 
</ul> 
</div> 
</div> 
</div> 
{% endblock %} 


{% block content %} 
<div class="container"> 
<div class="page-header"> 
<hi>Hello, {{ name }}!</h1i> 
</div> 
</div> 
{% endblock %} 


Jinja2 中 的 extends 指令 从 Flask-Bootstrap 中 导入 bootstrap/base.html， 从 而 实现 模板 继承 。 
Flask-Bootstrap 的 基 模 板 提供 了 一 个 网 页 骨架 ， 引 入 了 Bootstrap 的 所 有 CSS 和 JavaScript 
文件 。 

上 面 这 个 user.html 模板 定义 了 3 个 区 块 ， 分 别名 为 title、navbar 和 content。 这 些 区 块 
都 是 基 模 板 提供 的 ， 可 在 衍生 模板 中 重新 定义 。titte 区 块 的 作用 很 明显 ， 其 中 的 内 容 会 
出 现在 演 染 后 的 HTML 文档 头 部 ， 放 在 <title> 标签 中 。navbar 和 content 这 两 个 区 块 分 
别 表示 页 面 中 的 导航 栏 和 主体 内 容 。 

在 这 个 模板 中 ，navbar 区 块 使 用 Bootstrap 组 件 定义 了 一 个 简单 的 导航 栏 。content 区 块 中 
有 个 <div> 容器 ， 其 中 包含 一 个 页 头 。 之 前 版 本 中 的 欢迎 消息 ， 现 在 就 放 在 这 个 页 头 里 。 
改动 之 后 的 应 用 如 图 3-1 所 示 。 






























































模板 | 25 





@ @ Flasky x 
< CO © localhost:5000/user/Dave 





Hello, Dave! 














3-1; 使 用 Bootstrap 的 模板 


如 果 你 从 GitHub 上 克隆 了 这 个 应 用 的 Git 仓库 ， 那 么 可 以 执行 git checkout 
3b 检 出 应 用 的 这 个 版 本 。 别 忘 了 在 你 的 虚拟 环境 中 安装 Flask-Bootstrap 包 。 
Bootstrap 官方 文档 (https://getbootstrap.com/docs/4.1/getting-started/introduction/) 
是 很 好 的 学 习 资 源 ， 有 很 多 可 以 直接 复制 粘贴 的 示例 。 








Flask-Bootstrap 的 base.html 模板 还 定义 了 很 多 其 他 区 块 ， 都 可 在 衍生 模板 中 使 用 。 表 3-2 
列 出 了 所 有 可 用 的 区 块 。 


表 3-2: Flask-Bootstrap 基 模板 中 定义 的 区 块 




















区 块 名 说 明 

doc 整个 HTML 文档 
html_attribs <html> 标签 的 属性 
html <html> 标签 中 的 内 容 
head <head> 标签 中 的 内 容 
title <title> 标签 中 的 内 容 
metas 一 组 <meta> 标签 
styles CSS 声明 
body_attribs <body> 标签 的 属性 
body <body> 标签 中 的 内 容 
navbar 用 户 定义 的 导航 栏 
content 用 户 定义 的 页 面 内 容 
scripts 文档 底部 的 JavaScript 声明 

















表 3-2 中 的 很 多 区 块 都 是 Flask-Bootstrap 自用 的 ， 如 果 直 接 覆 盖 可 能 会 导致 一 些 问题 。 例 
如 ，Bootstrap 的 CSS 和 JavaScript 文件 在 styles 和 scripts 区 块 中 声明 。 如 果 应 用 需要 向 
已 经 有 内 容 的 块 中 添加 新 内 容 ， 必 须 使 用 Jinja2 提供 的 super() 函数 。 例 如 ， 如 果 要 在 衍 
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生 模 板 中 添加 新 的 JavaScript 文件 ， 需 要 这 么 定义 scripts 区 块 : 


{% block scripts %} 
{{ super() }} 


<script type="text/javascript" src="my-script.js"></script> 
{% endblock %} 


3.3 ”上 自 定 义 错误 页 


如 果 你 在 浏览 器 的 地 址 栏 中 输入 了 无 效 的 路 由 ， 会 看 到 一 个 状态 码 为 404 的 错误 页 面 。 与 
使 用 Bootstrap 的 页 面相 比 ， 现 在 这 个 错误 页 面 太 简陋 、 平 良 ， 而 且 与 现 有 页 面 不 一 致 。 


像 和 常规 路 由 一 样 ，Flask 允许 应 用 使 用 模板 自 定义 错误 页 面 。 最 常见 的 错误 代码 有 两 个 : 
404， 客 户 端 请 求 未 知 页 面 或 路 由 时 显示 ; 500， 应 用 有 未 处 理 的 异常 时 显示 。 示 例 3-6 使 
用 app.errorhandler 装饰 器 为 这 两 个 错误 提供 自 定 义 的 处 理 函 数 。 


示例 3-6 hello.py: 自 定义 错误 页 下 
@app.errorhandler(404) 
def page_not_found(e): 
return render_template('404.html'), 404 











































































































@app.errorhandler(500) 
def internal_server_error(e): 
return render_template('500.html'), 500 


与 视图 函数 一 样 ， 错 误 处 理 函 数 也 返回 一 个 响应 。 此 外 ， 错 误 处 理 函 数 还 要 返回 与 错误 对 
应 的 数字 状态 码 。 状 态 码 可 以 直接 通过 第 二 个 返回 值 指定 。 


错误 处 理 函 数 中 引用 的 模板 也 需要 我 们 编写 。 这 些 模板 应 该 和 常规 页 面 使 用 相同 的 布局 ， 
因此 要 有 一 个 导航 栏 和 显示 错误 消息 的 页 头 。 


写 这 些 模板 最 直接 的 方法 是 复制 templates/user.html， 分 别 创 建 templates/404.html 和 
templates/500.html， 然 后 把 这 两 个 文件 中 的 页 头 元 素 改 为 相应 的 错误 消息 。 但 是 这 么 做 会 
带 来 很 多 重复 劳 双 
Jinja2 的 模板 继承 机 制 可 以 帮助 我 们 解决 这 一 问题 。Flask-Bootstrap 提供 了 一 个 具有 页 面 基 
本 布局 的 基 模 板 ， 同样， 应 用 也 可 以 定义 一 个 具有 统一 页 面 布局 的 基 模 板 ， 其 中 包含 导航 
栏 ， 而 页 面 内 容 则 留 给 衍生 模板 定义 。 示 例 3-7 展示 了 templates/base.html 的 内 容 ， 这 是 一 
个 继承 自 bootstrap/base.html 的 新 模板 ， 其 中 定义 了 导航 栏 。 这 个 模板 本 身 也 可 作为 其 他 模 
板 的 二 级 基 模 板 ， 例 如 templates/user.html、templates/404.html 和 templates/500.html。 


示例 3-7 templates/base.html: 包含 导航 栏 的 应 用 基 模 板 


{% extends "bootstrap/base.html" %} 
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{% block title %}FLasky{% endblock %} 


{% block navbar %} 
<div class="navbar navbar-inverse" role="navigation"> 
<div class="container"> 
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<div cLass="navbar-header "> 
<button type="button" class="navbar-toggle" 
data-toggle="collapse" data-target=".navbar-collapse"> 
<span class="sr-only">Toggle navigation</span> 
<span class="icon-bar"></span> 
<span class="icon-bar"></span> 
<span class="icon-bar"></span> 
</button> 
<a class="navbar-brand" href="/">Flasky</a> 
</div> 
<div class="navbar-collapse collapse'"> 
<ul class="nav navbar-nav"> 
<li><a href="/">Home</a></li> 
</ul> 
</div> 
</div> 
</div> 
{% endblock %} 


{% block content %} 
<div class="container"> 
{% block page_content %}{% endblock %} 

</div> 

{% endblock %} 
这 个 模板 中 的 content 区 块 里 只 有 一 个 <div> 容器 ， 其 中 包含 一 个 新 的 空 区 块 ， 名 为 page 
content， 区 块 中 的 内 容 由 衍生 模板 定义 。 
现在 ， 应 用 中 的 模板 继承 自 这 个 模板 ， 而 不 直接 继承 自 Flask-Bootstrap 的 基 模 板 。 通 过 继 
承 templates/base.html 模板 编写 自 定义 的 404 错误 页 面 就 简单 了 ， 如 示例 3-8 所 示 。500 错 
误 页 面 的 编写 方式 与 此 类 似 ， 参 见 本 应 用 的 GitHub 仓库 。 


示例 3-8 ”templates/404.html: 使 用 模板 继承 机 制 自 定义 404 错误 页 面 
{% extends "base.html" %} 


















































{% block title %}Flasky - Page Not Found{% endblock %} 


{% block page_content %} 
<div class="page-header"> 
<h1>Not Found</h1> 

</div> 
{% endblock %} 


错误 页 面 在 浏览 器 中 的 显示 效果 如 图 3-2 所 示 。 























@ @ Flasky - Page Not Found 


< CO © localhost:5000/invalio 





Not Found 











3-2: 自 定义 的 404 错误 页 面 
templates/user.html 模板 也 可 以 通过 继承 这 个 基 模 板 来 简化 内 容 ， 如 示例 3-9 所 示 。 
示例 3-9 templates/user.html: 使 用 模板 继承 机 制 简化 页 面 模板 


{% extends "base.html" %} 
{% block title %}Flasky{% endblock %} 


{% block page_content %} 

<div class="page-header"> 
<hi>Hello, {{ name }}!</h1> 

</div> 

{% endblock %} 





如 果 你 从 GitHub 上 克隆 了 这 个 应 用 的 Git 仓库 ， 那 么 可 以 执行 git checkout 
3c 检 出 应 用 的 这 个 版 本 。 











3.4 链接 


任何 具有 多 个 路 由 的 应 用 都 需要 可 以 连接 不 同 页 面 的 链接 ， 例 如 导航 栏 。 

在 模板 中 直接 编写 简单 路 由 的 URL 链接 不 难 ， 但 对 于 包含 可 变 部 分 的 动态 路 由 ， 在 模板 
中 构建 正确 的 URL 就 很 困难 了 。 而 且 ， 直 接 编写 URL 会 对 代码 中 定义 的 路 由 产生 不 必要 
的 依赖 关系 。 如 果 重 新 定义 路 由 ， 模 板 中 的 链接 可 能 会 失效 。 

为 了 避免 这 些 问 题 ，Flask 提供 了 urL_for() 辅助 函数 ， 它 使 用 应 用 的 URL 映射 中 保存 的 
信息 生成 URL。 

url_for() 函数 最 简单 的 用 法 是 以 视图 函数 名 (或 者 app.add_url_route() 定义 路 由 时 
使 用 的 端点 名 ) 作为 参数 ， 返 回 对 应 的 URL。 例 如 ， 在 当前 版 本 的 hello.py 应 用 中 调用 
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url_for('index') 得 到 的 结果 是 /， 即 应 用 的 根 URL。 调 用 urL_for('index' ，_externaL=True) 
返回 的 则 是 绝对 地 址 ， 在 这 个 示例 中 是 http://localhost:5000/。 


生成 连接 应 用 内 不 同 路 由 的 链接 时 ， 使 用 相对 地 址 就 足够 了 。 如 果 要 生成 
在 浏览 器 之 外 使 用 的 链接 ， 则 必须 使 用 绝对 地 址 ， 例 如 在 电子 邮件 中 发 送 
的 链接 。 























使 用 url_for() 生成 动态 URL 时 ， 将 动态 部 分 作为 关键 字 参 数 传人 和信。 例如，urL_for('user ' ， 
name='john' ，_external=True) 的 返回 结果 是 http://localhost:5000/user/john。 


传 给 urL_for() 的 关键 字 参 数 不 仅 限于 动态 路 由 中 的 参数 ， 非 动态 的 参数 也 会 添加 到 查询 
字符 串 中 。 例 如 ，urL_for('user' ，name=' john' ，page=2，version=1) 的 返回 结果 是 /user/ 
john?page=2&version=1。 


3.5 ”静态 文件 


Web 应 用 不 是 仅 由 Python 代码 和 模板 组 成 。 多 数 应 用 还 会 使 用 静态 文件 ， 例 如 模板 中 
HTML 代码 引用 的 图 像 、JavaScript 源码 文件 和 CSS。 


你 可 能 还 记得 ， 在 第 2 章 中 审查 hello.py 应 用 的 URL 映射 时 ， 其 中 有 一 个 static 路 由 。 
这 是 Flask 为 了 支持 静态 文件 而 自动 添加 的 ， 这 个 特殊 路 由 的 URL 是 /static/<filename>。 
例如 ， 调 用 url_for('static'，filename='css/styles.css'，_external=True) 得 到 的 结果 
是 http://localhost:5000/static/css/styles.css。 


默认 设置 下 ，Flask 在 应 用 根 目录 中 名 为 static 的 子 目录 中 寻找 静态 文件 。 如 果 需 要， 可 在 
static 文件 夹 中 使 用 子 文件 夹 存放 文件 。 服 务 器 收 到 映射 到 static 路 由 上 的 URL 后 ， 生 成 
的 响应 包含 文件 系统 中 对 应 文件 里 的 内 容 。 


示例 3-10 展示 了 如 何在 应 用 的 基 模 板 中 引入 favicon.ico 图 标 。 这 个 图 标 会 显示 在 浏览 器 的 
地 址 栏 中 。 


示例 3-10 ”templates/base.html: 定义 收藏 夹 图 标 

{% block head %} 

{{ super() }} 

<link rel="shortcut icon" href="{{ url_for('static', filename='favicon.ico') }}" 
type="image/x-icon"> 

<Link rel="icon" href="{{ url_for('static', filename='favicon.ico') }}" 
type="image/x-icon"> 

{% endblock %} 


这 个 图 标的 声明 插入 head 区 块 的 末尾 。 注 意 ， 为 了 保留 基 模 板 中 这 个 区 块 里 的 原始 内 容 ， 
我 们 调用 了 super()。 
























































如 果 你 从 GitHub 上 克隆 了 这 个 应 用 的 Git 仓库 ， 那 么 可 以 执行 git checkout 
3d 检 出 应 用 的 这 个 版 本 。 








3.6 ”使 用 Flask-Moment 本 地 化 日 期 和 时 间 


如 果 Web 应 用 的 用 户 来 自 世 界 各 地 ， 那 么 处 理 日 期 和 时 间 可 不 是 一 个 简单 的 任务 。 


服务 器 需要 统一 时 间 单 位 ， 这 和 用 户 所 在 的 地 理 位 置 无 关 ， 所 以 一 般 使 用 协调 世界 时 
(UTC，coordinated universal time)。 不 过 用 户 看 到 UTC 格式 的 时 间 会 感到 困惑 ， 他 们 更 希 
望 看 到 当地 时 间 ， 而 且 采 用 当地 惯用 的 格式 。 


要 想 在 服务 器 上 只 使 用 UTC 时 间 ， 一 个 优雅 的 解决 方案 是 ， 把 时 间 单 位 发 送 给 Web 浏览 
器 ， 转 换 成 当地 时 间 ， 然 后 用 JavaScript 演 染 。Web 浏览 器 可 以 更 好 地 完成 这 一 任务 ， 
为 它 能 获取 用 户 计算 机 中 的 时 区 和 区 域 设置 。 

有 一 个 使 用 JavaScript 开发 的 优秀 客户 端 开源 库 ， 名 为 Moment.js， 它 可 以 在 浏览 器 中 泻 染 
日 期 和 时 间 。Flask-Moment 是 一 个 Flask 扩展 ， 能 简化 把 Moment.js 集成 到 Jinja2 模板 中 
的 过 程 。Flask-Moment 使 用 pip 安装 : 


(venv) $ pip install flask-moment 
这 个 扩展 的 初始 化 方法 与 Flask-Bootstrap 类 似 ， 所 需 的 代码 如 示例 3-11 所 示 。 


示例 3-11 hello.py: 初始 化 Flask-Moment 


from flask_moment import Moment 
moment = Moment(app) 


除了 Moment.js，Flask-Moment 还 依赖 jQuery.js。 因 此 ， 要 在 HTML 文档 的 某 个 地 方 引 入 
这 两 个 库 ， 可 以 直接 引入 ， 这 样 可 以 选择 使 用 哪个 版 本 ， 也 可 以 使 用 扩展 提供 的 辅助 函 
数 ， 从 内 容 分 发 网 络 (CDN，content delivery network) 中 引入 通过 测试 的 版 本 。Bootstrap 
已 经 引入 了 jQuery.js， 因 此 只 需 引 入 Moment.js 即 可 。 示 例 3-12 展示 了 如 何在 基 模 板 的 
scripts 块 中 引入 这 个 库 ， 同 时 还 保留 基 模 板 中 定义 的 原始 内 容 。 注 意 ， 这 个 区 块 在 Flask- 
Bootstrap 的 基 模板 中 已 经 预定 义 ， 因 此 放 在 templates/base.html 的 任何 位 置 都 行 。 


示例 3-12 templates/base.html: 引入 Moment.js 库 


{% block scripts %} 
{{ super() }} 


{{ moment.include moment() }} 

{% endblock %} 
为 了 处 理 时 间 戳 ，Flask-Moment 向 模板 开放 了 moment 对 象 。 示 例 3-13 中 的 代码 把 变量 
current_time 传 入 模板 进行 演 染 。 
示例 3-13 ”hello.py: 添加 一 个 datetime 变量 


from datetime import datetime 



























































@app.route('/') 
def index(): 
return render_template('index.html', 
current_time=datetime.utcnow()) 





示例 3-14 展示 了 如 何 泻 染 模 板 变 量 current_time。 
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代码 3-14 templates/index.html: 使 用 Flask-Moment 泻 染 时 间 稚 


<p>The local date and time is {{ moment(current time).format('LLL') }}.</p> 
<p>That was {{ moment(current_time).fromNow(refresh=True) }}</p> 


format('LLL') 函数 根据 客户 端 计 算 机 中 的 时 区 和 区 域 设置 浑 染 日 期 和 时 间 。 参 数 决 定 了 
泻 染 的 方式 ， 从 'L' 到 'LLLL' 分 别 对 应 不 同 的 复杂 度 。format() 函数 还 可 接受 很 多 自 定义 
的 格式 说 明 符 。 


第 二 行 中 的 fromNow() 浑 染 相对 时 间 惟 ， 而 且 会 随 着 时 间 的 推移 自动 刷新 显示 的 时 间 。 这 
个 时 间 惟 最 开始 显示 为 “a few seconds ago”， 但 设 定 refresh=True 参数 后 ， 其 内 容 会 随 着 
时 间 的 推移 而 更 新 。 如 果 一 直 竺 在 这 个 页 面 ， 几 分 钟 后 会 看 到 显示 的 文本 变 成 “a minute 


先 如 


ag0”“2 minutes ago”， 等 等 。 


在 index.html 模板 中 添加 这 两 个 时 间 惟 之 后 ，http:Wlocalhost:5000/ 路 由 对 应 的 页 面 如 图 3-3 
所 示 。 




















©09 Fasy 


€ (Si 合 @Iiocalhost:5000 





Hello World! 


The local date and time is July 18, 2017 10:23 AM. 


That was afew seconds ago. 














3-3: 页 面 中 的 两 个 时 间 戳 由 Flask-Moment 处 理 


如 果 你 从 GitHub 上 克隆 了 这 个 应 用 的 Git 仓库 ， 那 么 可 以 执行 gqit checkout 
3e 检 出 应 用 的 这 个 版 本 。 





Flask-Moment 实现 了 Momentjs 的 format()、fromNow()、fromTime()、caLendar()、vatLueof() 
和 unix() 等 方法 。 请 查阅 Moment.js 的 文档 (http://momentjs.com/docs/#/displaying/)， 学 
习 这 个 库 提 供 的 全 部 格式 化 选项 。 








Flask-Moment 假定 服务 器 端 应 用 处 理 的 时 间 改 是 “纯正 的 ”datetime 对 象 ， 
且 使 用 UTC 表示。 关于 纯正 和 细致 的 日 期 和 时 间 对 象 “ 的 说 明 ， 请 阅读 标准 
库 中 datetime 包 的 文档 (https://docs.python.org/3.6/library/datetime.html) 。 





























Flask-Moment 泻 染 的 时 间 戳 可 实现 多 种 语言 的 本 地 化 。 语 言 可 在 模板 中 选择 ， 方 法 是 在 引 
入 Momentjs 之 后 ， 立 即 把 两 个 字母 的 语言 代码 传 给 Locate() 函数 。 例 如 ， 配 置 Moment 
js 使 用 西班牙 语 的 方式 如 下 : 


{% block scripts %} 

{{ super() }} 

{{ moment.include moment() }} 
{{ moment.locale('es') }} 

{% endblock %} 


使 用 本 章 介绍 的 各 项 技术 ， 你 应 该 能 为 应 用 编写 出 现代 化 且 对 用 户 友好 的 网 页 。 下 一 章 将 
介绍 本 章 没 有 涉及 的 一 个 模板 功能 ， 即 如 何 通过 Web 表单 与 用 户 交 互 。 











注 1: 纯正 的 时 间 戳 ， 英 文 为 naive time， 指 不 包含 时 区 的 时 间 惟 ， 细 致 的 时 间 惟 ， 英 文 为 aware time， 指 
包含 时 区 的 时 间 戳 。 译 者 注 
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第 4 章 


Web 表 单 





第 3 章 编 写 的 模板 都 是 单 向 的 ， 所 有 信息 都 从 服务 器 流向 用 户 。 然 而 ， 对 多 数 应 用 来 说 ， 
还 需要 沿 相 反 的 方向 流动 信息 ， 把 用 户 提 供 的 数据 交 给 服务 器 来 处 理 。 

使 用 HTML 可 以 创建 Web 表单 ， 供 用户 填 写 信息 。 表 单数 据 由 Web 浏览 器 提交 给 服务 
器 ， 这 一 过 程 通常 使 用 P0ST 请 求 。 第 2 章 介 绍 的 Flask 请 求 对 象 包含 客户 端 在 请 求 中 发 送 
的 全 部 信息 ， 对 包含 表单 数据 的 PosT 请 求 来 说 ， 用 户 填 写 的 信息 通过 request.form 访问 。 

尽管 Flask 的 请 求 对 象 提供 的 信息 足以 处 理 Web 表单 ， 但 有 些 任务 很 单调 ， 而 且 要 重复 操 
作 。 比 如 ， 生 成 表单 的 HTML 代码 和 验证 提交 的 表单 数据 。 

Flask-WTF 扩展 可 以 把 处 理 Web 表单 的 过 程 变 成 一 种 愉悦 的 体验 。 这 个 扩展 对 独立 的 
WTForms 包 进 行 了 包装 ， 方便 集成 到 Flask 应 用 中 。 

Flask-WTF 及 其 依赖 可 使 用 pip 安装 : 


(venv) $ pip install flask-wtf 


4.1 配置 


与 其 他 多 数 扩展 不 同 ，Flask-WTF 无 须 在 应 用 层 初始 化 ， 但 是 它 要 求 应 用 配置 一 个 密 钥 。 
密 钥 是 一 个 由 随机 字符 构成 的 唯一 字符 串 ， 通 过 加 密 或 签名 以 不 同 的 方式 提升 应 用 的 安全 
性 。Flask 使 用 这 个 密 钥 保 护 用 户 会 话 ， 以 防 被 自 改 。 每 个 应 用 的 密 钥 应 该 不 同 ， 而 且 不 
能 让 任何 人 知道 。 示 例 4-1 展示 如 何在 Flask 应 用 中 配置 密 铀 。 


示例 4-1 hello.py: 配置 Flask-WTF 


app = Flask(__name_ ) 
app.config['SECRET_KEY'] = 'hard to guess string’ 
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app.config 字典 可 用 于 存储 Flask、 扩 展 和 应 用 自身 的 配置 变量 。 使 用 标准 的 字典 句法 就 
能 把 配置 添加 到 app.config 对 象 中 。 这 个 对 象 还 提供 了 一 些 方法 ， 可 以 从 文件 或 环境 中 导 
入 配置 。 第 7 章 将 介绍 管理 大 型 应 用 配置 的 合理 方式 。 


Flask-WTF 之 所 以 要 求 应 用 配置 一 个 密 钥 ， 是 为 了 防止 表单 遭 到 跨 站 请 求 伪 造 (CSRF， 
cross-site request forgery) 攻击 。 亚 意 网 站 把 请 求 发 送 到 被 攻击 者 已 登录 的 其 他 网 站 时 ， 就 
会 引发 CSRF 攻击 。Flask-WTF 为 所 有 表单 生成 安全 令 牌 ， 存 储 在 用 户 会 话 中 。 令 牌 是 一 
种 加 密 签名 ， 根 据 密 钥 生 成 。 


























为 了 增强 安全 性 ， 密 钥 不 应 该 直接 写 人 源码 ， 而 要 保存 在 环境 变量 中 。 这 一 
技术 在 第 7 章 介绍 。 








4.2 ”表单 类 


使 用 Flask-WTF 时 ， 在 服务 器 端 ， 每 个 Web 表单 都 由 一 个 继承 自 FlaskForn 的 类 表示 。 这 
个 类 定义 表单 中 的 一 组 字段 ， 每 个 字段 都 用 对 象 表示 。 字 段 对 象 可 附属 一 个 或 多 个 验证 函 
数 。 验 证 函数 用 于 验证 用 户 提 交 的 数据 是 否 有 效 。 

示例 4-2 是 一 个 简单 的 Web 表单 ， 包 含 一 个 文本 字段 和 一 个 提交 按钮 。 


示例 4-2 hello.py: 定义 表单 类 
from flask_wtf import FlaskForm 
from wtforms import StringField, SubmitField 
from wtforms.validators import DataRequired 











class NameForm(FLaskForm) : 
name = StringField('What is your name?', validators=[DataRequired()]) 
submit = SubmitField('Submit') 


这 个 表单 中 的 字段 都 定义 为 类 变量 ， 而 各 个 类 变量 的 值 是 相应 字段 类 型 的 对 象 。 在 这 个 
示例 中 ，NameForm 表单 中 有 一 个 名 为 nane 的 文本 字段 和 一 个 名 为 submit 的 提交 按钮 。 
StringField 类 表示 属性 为 type="text" 的 HTML <input> 元 素 。SubmitField 类 表示 属性 
为 type="submit" 的 HTML <input> 元 素 。 字 有 段 构造 函数 的 第 一 个 参数 是 把 表单 泻 染 成 
HTML 时 使 用 的 标注 (label)。 


StringField 构造 国 数 中 的 可 选 参数 validators 指定 一 个 由 验证 函数 组 成 的 列表 ， 在 接受 
用 户 提交 的 数据 之 前 验证 数据 。 验 证 函数 DataRequired() 确保 提交 的 字段 内 容 不 为 空 。 





FLaskForm 基 类 由 Flask-WTF 扩展 定义 ， 所 以 要 从 flask_wtf 中 导入 。 然 而 ， 
字段 和 验证 函数 却 是 直接 从 WTForms 包 中 导入 的 。 


WTForms 支持 的 HTML 标准 字段 如 表 4-1 所 示 。 
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表 4-1: WTForms 支 持 的 HTML 标 准 字段 




























































































字段 类 型 说 明 

BooleanField 复 选 框 ， 值 为 True 和 False 
DateField 文本 字段 ， 值 为 datetime.date 格式 
DateTimeField 文本 字段 ， 值 为 datetime.datetime 格式 
DecimalField 文本 字段 ， 值 为 decimal.Decimal 
FileField 文件 上 传 字段 

HiddenField 隐藏 的 文本 字段 

MultipleFileField 多 文件 上 传 字段 

FieldList 一 组 指定 类 型 的 字段 

FloatField 文本 字段 ， 值 为 浮 点 数 

FormField 把 一 个 表单 作为 字段 柑 入 另 一 个 表单 
IntegerField 文本 字段 ， 值 为 整数 

PasswordField 密码 文本 字段 

RadioField 一 组 单 选 按钮 

SelectField 下 拉 列 表 

SelectMultipleField 下 拉 列 表 ， 可 选择 多 个 值 
SubmitField 表单 提交 按钮 

StringField 文本 字段 

TextAreaField 多 行文 本 字段 
WTForms 内 建 的 验证 函数 如 表 4-2 所 示 。 
表 4-2: WTForms 验 证 函数 

验证 函数 说 明 

DataRequired 确保 转换 类 型 后 字段 中 有 数据 

Email 验证 电子 邮件 地 址 

EqualTo 比较 两 个 字段 的 值 ， 和 常用 于 要 求 输入 两 次 密码 进行 确认 的 情况 
InputRequired 确保 转换 类 型 前 字段 中 有 数据 

IPAddress 验证 IPv4 网 络 地 址 

Length 验证 输入 字符 串 的 长 度 

MacAddress 验证 MAC 地 址 

NumberRange 验证 输入 的 值 在 数字 范围 之 内 

Optional 允许 字段 中 没有 输入 ， 将 跳 过 其 他 验证 函数 

Regexp 使 用 正则 表达 式 验 证 输入 值 

URL 验证 URL 

UUID 验证 UUID 

AnyOf 确保 输入 值 在 一 组 可 能 的 值 中 

Noneof 确保 输入 值 不 在 一 组 可 能 的 值 中 
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4.3 ”把 表单 泻 染 成 HTML 


表单 字段 是 可 调用 的 ， 在 模板 中 调用 后 会 泻 染 成 HTML。 假 设 视图 函数 通过 forn 参数 把 
一 个 NameForn 实例 传人 模板， 在 模板 中 可 以 生成 一 个 简单 的 HTML 表单 ， 如 下 所 示 ， 
<form method="POST"> 
{{ form.hidden tag() }} 
{{ form.name.label }} {{ form.name() }} 


{{ form.submit() }} 
</form> 


注意 ， 除 了 name 和 submit 字段 ， 这 个 表单 还 有 个 form.hidden_tag() 元 素 。 这 个 元 素 生 成 
一 个 隐藏 的 字段 ， 供 Flask-WTEF 的 CSRF 防护 机 制 使 用 。 


当然 ， 这 种 方式 谊 染 出 的 表单 还 很 简陋 。 调 用 字段 时 传 入 的 任何 关键 字 参 数 都 将 转换 成 字 
段 的 HTML 属性 。 例 如 ， 可 以 为 字段 指定 id 或 ctass 属性 ， 然 后 为 其 定义 CSS 样式 : 
<form method="POST"> 
{{ form.hidden tag() }} 
{{ form.name.label }} {{ form.name(id='my-text-field') }} 


{{ form.submit() }} 
</form> 


即便 能 指定 HTML 属性 ， 但 按照 这 种 方式 演 染 及 美化 表单 的 工作 量 还 是 很 大 ， 所 以 在 条 件 
允许 的 情况 下 ， 最 好 使 用 Bootstrap 的 表单 样式 。Flask-Bootstrap 扩展 提供 了 一 个 高 层级 的 
辅助 函数 ， 可 以 使 用 Bootstrap 预定 义 的 表单 样式 演 染 整个 Flask-WTF 表单 ， 而 这 些 操作 
只 需 一 次 调用 即 可 完成 。 使 用 Flask-Bootstrap， 上 述 表 单 可 以 用 下 面 的 方式 渲染 


{% import "bootstrap/wtf.html" as wtf %} 
{{ wtf.quick_form(form) }} 


import 指令 的 使 用 方法 和 普通 Python 代码 一 样 ， 通 过 它 可 以 导入 模板 元 素 ， 在 多 个 模板 
中 使 用 。 导 入 的 bootstrap/wtf.html 文件 中 定义 了 一 个 使 用 Bootstrap 演 染 Flask-WTF 表单 
对 象 的 辅助 函数 。wtf.quick_form() 函数 的 参数 为 Flask-WTF 表单 对 象 ， 使 用 Bootstrap 的 
默认 样式 演 染 传人 的 表单 。hello.py 的 完整 模板 如 示例 4-3 所 示 。 


示例 4-3 ”templates/index.html: 使 用 Flask-WTF 和 Flask-Bootstrap 演 染 表单 


{% extends "base.html" %} 
{% import "bootstrap/wtf.html" as wtf %} 











































































































{% block title %}Flasky{% endblock %} 


{% block page_content %} 
<div class="page-header"> 
<hi>Hello, {% if name %}{{ name }}{% else %}Stranger{% endif %}!</h1> 
</div> 
{{ wtf.quick_form(form) }} 
{% endblock %} 


模板 的 内 容 区 现在 有 两 部 分 。 第 一 部 分 是 页 头 ， 显 示 欢 迎 消息 。 这 里 用 到 了 一 个 模板 条 
件 语 句 。Jinja2 的 条 件 语 名 格式 为 { if condition %}...{% else %}...{% endif %}。 如 
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果 条 件 的 计算 结果 为 True， 那 么 演 染 if 和 else 指令 之 间 的 内 容 。 如 果 条 件 的 计算 结果 
为 False， 则 泻 染 else 和 endif 指令 之 间 的 内 容 。 在 这 个 例子 中 ， 如 果 定 义 了 name 变量 ， 
则 演 染 Hello，{{ name }}!， 耕 则 演 染 Hello，Stranger!。 内 容 区 的 第 二 部 分 使 用 wtf. 
quick_form() 函数 演 染 NameForm 对 象 。 


4.4 在 视图 函数 中 处 理 表 单 


在 新 版 hello.py 中 ， 视 图 函数 index() 有 两 个 任务 : 一 是 演 染 表单 ， 二 是 接收 用 户 在 表单 
中 填写 的 数据 。 示 例 4-4 是 更 新 后 的 index() 视图 函数 。 


示例 4-4 hello.py: 使 用 GET 和 POST 请 求 方法 处 理 Web 表单 


@app.route('/', methods=['GET', 'POST']) 
def index(): 
name = None 
form = NameForm() 
if form.validate on_submit(): 
name = form.name.data 


























form.name.data = "" 
return render_template('index.html', form=form, name=name) 


app.route 装饰 器 中 多 出 的 methods 参数 告诉 Flask， 在 URL 映射 中 把 这 个 视图 函数 注册 为 
GET 和 PoST 请 求 的 处 理 程序 。 如 果 没 指定 methods 参数 ， 则 只 把 视图 函数 注册 为 GET 请 求 的 
处 理 程序 。 


这 里 有 必要 把 PoST 加 入 方法 列表 ， 因 为 更 常 使 用 POST 请 求 处 理 表单 提交 。 表 单 也 可 以 通过 
GET 请 求 提交 ， 但 是 GET 请 求 没有 主体 ， 提 交 的 数据 以 查询 字符 串 的 形式 附加 到 URL 中 ,在 
浏 览 器 的 地 址 栏 中 可 见 。 基 于 这 个 以 及 其 他 多 个 原因 ， 处 理 表 单 提 交 儿 乎 都 使 用 PosT 请 求 。 


局 部 变量 name 用 于 存放 表单 中 输入 的 有 效 名 字 ， 如 果 没 有 输入 ， 其 值 为 None。 如 上 述 代 
码 所 示 ， 我 们 在 视图 函数 中 创建 了 一 个 NameForm 实例 ， 用 于 表示 表单 。 提 交 表 单 后 ， 如 果 
数据 能 被 所 有 验证 函数 接受 ， 那 么 validate_on_submit() 方法 的 返回 值 为 True， 否 则 返回 
FaLse。 这 个 函数 的 返回 值 决定 是 重新 演 染 表单 还 是 处 理 表单 提交 的 数据 。 

用 户 首次 访问 应 用 时 ， 服 务 器 会 收 到 一 个 没有 表单 数据 的 GET 请 求 ， 所 以 validate_on_ 
submit() 将 返回 False。 此 时 ，if 语句 的 内 容 将 被 跳 过 ， 对 请 求 的 处 理 只 是 泻 染 模板 ， 并 
传人 表单 对 象 和 值 为 None 的 name 变量 作为 参数 。 用 户 会 看 到 浏览 器 中 显示 了 一 个 表单 。 


用 户 提交 表单 后 ， 服 务 器 会 收 到 一 个 包含 数据 的 PosT 请 求 。validate_on_submit() 会 调用 名 
字 字 段 上 依附 的 DataRequired() 验证 函数 。 如 果 名 字 不 为 空 ， 就 能 通过 验证 ，validate_on_ 
submit() 返回 True。 现 在 ， 用 户 输入 的 名 字 可 通过 字段 的 data 属性 获取 。 在 if 语句 中 ， 把 
名 字 赋 值 给 局 部 变量 name， 然 后 再 把 data 属性 设 为 空 字 符 串 ， 清 空 表单 字段 。 因 此 ， 再 次 
泻 染 这 个 表单 时 ， 各 字段 中 将 没有 内 容 。 最 后 一 行 调用 render_template() 函数 泻 染 模板 ， 
但 这 一 次 参数 name 的 值 为 表单 中 输入 的 名 字 ， 因 此 会 显示 一 个 针对 该 用 户 的 欢迎 消息 。 































































































如 果 你 从 GitHub 上 克隆 了 这 个 应 用 的 Git 仓库 ， 那 么 可 以 执行 git checkout 
4a 检 出 应 用 的 这 个 版 本 。 

















示 了 此 时 应 用 的 样子 。 


图 4-1 是 用 户 首次 访问 网 站 时 浏览 器 显示 的 表单 。 用 户 提 交 名 字 后 ， 应 用 会 生成 一 个 针对 
该 用 户 的 欢迎 消息 。 欢 迎 消息 下 方 还 是 会 显示 这 个 表单 ， 以 便 用 户 输入 新 名 字 。 


图 4.2 显 
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< C 合 @Iiocalhost:5000 





Hello, Stranger! 


What is your name? 


| 


Submit 














图 4-1: Flask-WTF Web 表单 





@@ fasy 


< GE 合 @Iocalhost:5000 





Hello, Dave! 


What is your name? 


Submit 














图 4-2: 提交 后 显示 的 Web 表单 
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如 果 用 户 提交 表单 之 前 没有 输入 名 字 ， 那 么 DataRequired() 验证 函数 会 捕获 这 个 错误 ， 如 
4-3 所 示 。 广 意 这 个 扩展 自动 提供 了 多 少 功能 。 这 说 明 ， 像 Flask-WTF 和 Flask-Bootstrap 
这 样 设计 良好 的 扩展 能 给 应 用 提供 十 分 强大 的 功能 。 
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Hello, Stranger! 


What is your name? 


Submit Please fill out this field. 














4-3: 验证 失败 后 显示 的 Web 表单 


4.5 重 定向 和 用 户 会 话 


前 一 版 hello.py 存在 一 个 可 用 性 问题 。 用 户 输入 名 字 后 提交 表单 ， 然 后 点 击 浏 览 器 的 刷新 
按钮 ， 会 看 到 一 个 莫名 其 妙 的 警告 ， 要 求 在 再 次 提交 表单 之 前 进行 确认 。 之 所 以 出 现 这 种 
情况 ， 是 因为 刷新 页 面 时 浏览 器 会 重新 发 送 之 前 发 送 过 的 请 求 。 如 果 前 一 个 请 求 是 包含 表 
单数 据 的 PosT 请 求 ， 刷 新 页 面 后 会 再 次 提交 表单 。 多 数 情况 下 ， 这 并 不 是 我 们 想 执行 的 操 
作 ， 因 此 浏览 器 才 要 求 用 户 确认 。 

很 多 用 户 不 理解 浏览 器 发 出 的 这 个 警告 。 鉴 于 此 ， 最 好 别 让 Web 应 用 把 PosT 请 求 作为 浏 
览 器 发 送 的 最 后 一 个 请 求 。 

这 种 需求 的 实现 方式 是 ， 使 用 重 定向 作为 P05T 请 求 的 响应 ， 而 不 是 使 用 常规 响应 。 重 定向 
是 一 种 特殊 的 响应 ， 响 应 内 容 包 含 的 是 URL， 而 不 是 HTML 代码 的 字符 串 。 浏 览 器 收 到 
这 种 响应 时 ， 会 向 重 定向 的 URL 发 起 GET 请 求 ， 显 示 页 面 的 内 容 。 这 个 页 面 的 加 载 可 能 
要 多 花 几 毫秒 ， 因 为 要 先 把 第 二 个 请 求 发 给 服务 器 。 除 此 之 外 ， 用 户 不 会 察觉 到 有 什么 不 
同 。 现 在 ， 前 一 个 请 求 是 GET 请 求 ， 所 以 刷新 命令 能 像 预期 的 那样 正常 运作 了 。 这 个 技巧 
称 为 Post / 重 定向 /Get 模式 。 


但 这 种 方法 又 会 引起 另 一 个 问题 。 应 用 处 理 PosT 请 求 时 ， 可 以 通过 form.name.data 获取 
用 户 输入 的 名 字 ， 然 而 一 旦 这 个 请 求 结 束 ， 数 据 也 就 不 见 了 。 因 为 这 个 PosT 请 求 使 用 重 定 
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向 处 理 ， 所 以 应 用 需要 保存 输入 的 名 字 ， 这 样 重 定向 后 的 请 求 才 能 获得 并 使 用 这 个 名 字 ， 
从 而 构建 真正 的 响应 。 

应 用 可 以 把 数据 存储 在 用 户 会 话 中 ， 以 便 在 请 求 之 间 “ 记 住 ”数据 。 用 户 会 话 是 一 种 私有 
存储 ， 每 个 连接 到 服务 器 的 客户 端 都 可 访问 。 我 们 在 第 2 章 介绍 过 用 户 会 话 ， 它 是 请 求 上 
下 文中 的 变量 ， 名 为 session， 像 标准 的 Python 字典 一 样 操 作 。 














默认 情况 下 ， 用 户 会 话 保 存在 客户 端 cookie 中 ， 使 用 前 面 设 置 的 密 钥 加 密 签 
名 。 如 果 自 改 了 cookie 的 内 容 ， 签 名 就 会 失效 ， 会 话 也 将 随 之 失效 。 











示例 4-5 是 index() 视图 函数 的 新 版 本 ， 实 现 了 重 定向 和 用 户 会 话 。 
示例 4-5 hello.py: 重 定向 和 用 户 会 话 


from flask import Flask, render_template, session, redirect, url_for 





@app.route('/', methods=['GET', 'POST']) 
def index(): 
form = NameForm() 
if form.validate on_submit(): 
session['name'] = form.name.data 
return redirect(url_for('index')) 
return render_template('index.html', form=form, name=session.get('name')) 


应 用 的 前 一 个 版 本 在 局 部 变量 name 中 存储 用 户 在 表单 中 输入 的 名 字 。 这 个 变量 现在 保存 在 
用 户 会 话 中 ， 即 session['name']， 所 以 在 两 次 请 求 之 间 能 记 住 输入 的 值 。 

现在 ， 包 含有 效 表单 数据 的 请 求 最 后 会 使 视图 函数 调用 redirect() 函数 。 这 是 Flask 提供 
的 辅助 函数 ， 用 于 生成 HTTP 重 定向 响应 。redirect() 函数 的 参数 是 重 定向 的 URL， 这 
里 使 用 的 重 定向 URL 是 应 用 的 根 URL， 因 此 重 定向 响应 本 可 以 写 得 更 简单 一 些 ， 写 成 
redirect('/')， 不 过 这 里 却 使 用 了 Flask 提供 的 URL 生成 函数 url_for() (参见 第 3 章 )。 


url_for() 函数 的 第 一 个 且 唯 一 必须 指定 的 参数 是 端点 名 ， 即 路 由 的 内 部 名 称 。 默 认 情 
况 下 ， 路 由 的 端点 是 相应 视图 函数 的 名 称 。 在 这 个 示例 中 ， 处 理 根 URL 的 视图 函数 是 
index()， 因 此 传 给 urL_for() 函数 的 名 字 是 index。 

最 后 一 处 改动 位 于 render_template() 函数 中 ， 现 在 我 们 使 用 session.get('name') 直接 从 
会 话 中 读 取 name 参数 的 值 。 与 普通 的 字典 一 样 ， 这 里 使 用 get() 获取 字典 中 键 对 应 的 值 ， 
可 以 避免 未 找到 键 时 抛 出 异常 。 如 果 指 定 的 键 不 存在 ， 则 get( ) 方法 返回 默认 值 None。 



























































如 果 你 从 GitHub 上 克隆 了 这 个 应 用 的 Git 仓库 ， 可 以 执行 git checkout 4b 
检 出 应 用 的 这 个 版 本 。 











使 用 这 个 版 本 的 应 用 ， 在 浏览 器 中 刷新 后 看 到 的 新 页 面 就 与 预期 一 样 了 。 
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4.6 ”闪现 消息 


请 求 完成 后 ， 有 时 需要 让 用 户 知道 状态 发 生 了 变化 ， 可 以 是 确认 消息 、 警 告 或 者 错误 提 
醒 。 一 个 典型 例子 是 ， 用 户 提 交 有 一 项 错误 的 登录 表单 后 ， 服 务 器 发 回 的 响应 重新 浑 染 登 
录 表 单 ， 并 在 表单 上 面 显示 一 个 消息 ， 提 示 用 户 名 或 密码 无 效 。 


Flask 本 身 内 置 这 个 功能 。 如 示例 4-6 所 示 ，flash() 函数 可 实现 这 种 效果 。 














示例 4-6 hello.py: 闪现 消息 


from flask import Flask, render_template, session, redirect, url_for, flash 


@app.route('/', methods=['GET', 'POST']) 
def index(): 
form = NameForm() 
if form.validate on_submit(): 
old_name = session.get('name') 
if oLd_name is not None and old_name != form.name.data: 
flash('Looks like you have changed your name!') 
session['name'] = form.name.data 
return redirect(url_for('index')) 
return render_template('index.html', 
form = form，name = session.get('name')) 


在 这 个 示例 中 ， 每 次 提交 的 名 字 都 会 和 存储 在 用 户 会 话 中 的 名 字 进 行 比较 ， 而 会 话 中 存储 
的 名 字 是 前 一 次 在 这 个 表单 中 提交 的 数据 。 如 果 两 个 名 字 不 一 样 ， 就 会 调用 flash() 函数 ， 
在 发 给 客户 端的 下 一 个 响应 中 显示 一 个 消息 。 


仅 调用 flash() 函数 并 不 能 把 消息 显示 出 来 ， 应 用 的 模板 必须 渲染 这 些 消息 。 最 好 在 基 模 
板 中 泻 染 办 现 消 息 ， 因 为 这 样 所 有 页 面 都 能 显示 需要 显示 的 消息 。Flask 把 get_flashed_ 
messages() 函数 开放 给 模板 ， 用 于 获取 并 泻 染 闪现 消息 ， 如 示例 4-7 所 示 。 


示例 4-7 ”templates/base.html: 演 染 闪现 消息 


{% block content %} 
<div class="container"> 
{% for message in get_fLashed_messages() %} 
<div class="alert alert-warning"> 
<button type="button" class="close" data-dismiss="alert">&times;</button> 
{{ message }} 
</div> 
{% endfor %} 
































{% block page_content %}{% endblock %} 
</div> 
{% endblock %} 


这 个 示例 使 用 Bootstrap 提供 的 CSS alert 样式 浑 染 警告 消息 (如 图 4-4 所 示 )。 











©09 ), 困 Fasey 


< C 合 @Iocalhost:5005 





Looks like you have changed your namel 


Hello, Susan! 


What is your name? 


Submit 











图 4-4: 闪现 消息 


这 里 使 用 了 循环 ， 因 为 在 之 前 的 请 求 循 环 中 每 次 调用 fLash() 函数 时 都 会 生成 一 个 消息 ， 
所 以 可 能 有 多 个 消息 在 排队 等 待 显示 。get_flashed_messages() 范 数 获取 的 消息 在 下 次 调 
用 时 不 会 再 次 返回 ， 因 此 闪现 消息 只 显示 一 次 ， 然 后 就 消失 了 。 











如 果 你 从 GitHub 上 克隆 了 这 个 应 用 的 Git 仓库 ， 那 么 可 以 执行 git checkout 
4c 检 出 应 用 的 这 个 版 本 。 








从 Web 表单 中 获取 用 户 输入 的 数据 是 多 数 应 用 都 需要 的 功能 ， 把 数据 保存 在 永久 存储 器 中 
也 是 一 样 。 第 5 章 将 介绍 如 何在 Flask 中 使 用 数据 库 。 
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第 5 章 





数据 库 


数据 库 按照 一 定 规则 保存 应 用 的 数据 ， 应 用 再 发 起 查询 ， 取 回 所 需 的 数据 。Web 应 用 最 党 
使 用 基于 关系 模型 的 数据 库 ， 这 种 数据 库 也 称 为 SQL 数据 库 ， 因 为 它们 使 用 结构 化 查询 语 
言 (SQL)。 不 过 近年 来 文档 数据 库 和 键 - 值 对 数据 库 成 了 流行 的 替代 选择 ， 这 两 种 数据 


库 合 称 NoSQL 数据 库 。 


5.1 _ SQL 数据 库 





关系 型 数据 库 把 数据 存储 在 表 中 ， 表 为 应 用 中 不 同 的 实体 建 模 。 例 如 ， 订 单 管理 应 用 的 数 








据 库 中 可 能 有 customers、products 和 orders 等 表 。 








表 中 的 列 数 是 固定 的 ， 行 数 是 可 变 的 。 列 定义 表 所 表示 的 实体 的 数据 属性 。 例 如 ，customers 
表 中 可 能 有 name、address、phone 等 列 。 表 中 的 行 定义 部 分 或 所 有 列 对 应 的 真实 数据 。 

表 中 有 个 特殊 的 列 ， 称 为 主键 ， 其 值 为 表 中 各 行 的 唯一 标识 符 。 表 中 还 可 以 有 称 为 外 键 的 
列 ， 引 用 同一 个 表 或 不 同 表 中 某 一 行 的 主键 。 行 之 间 的 这 种 联系 称 为 关系 ， 这 正 是 关系 型 











数据 库 模 型 的 基础 。 








5-1 展示 了 一 个 简单 数据 库 的 关系 图 。 

















这 个 数据 库 中 有 两 个 表 ， 分 别 存储 用 户 和 用 户 角 





色 。 连 接 两 个 表 的 线 代表 两 个 表 之 间 的 关系 。 








id 
username 


password 
role_id 











图 5-1: 关系 型 数据 库 示例 
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数据 库 结 构 的 这 种 图 示 法 称 为 实体 - 关系 图 。 其 中 ， 方 框 表 示 数 据 库 表 ， 里 面 列 出 表 的 
属性 (或 列 )。roles 表 存 储 所 有 可 用 的 用 户 角色 ， 每 个 角色 都 使 用 一 个 唯一 的 id 值 ( 即 
表 的 主键 ) 进行 标识 。users 表 存 储 用 户 ， 每 个 用 户 也 有 了 唯一 的 id 值 。 除 了 id 主键 之 外 ， 
roles 表 中 还 有 name 列 ，users 表 中 还 有 username 和 password 列 。 


users 表 中 的 role_id 列 是 外 键 。 连 接 roles.id 和 users.role_id 两 列 的 线 表 示 两 个 表 之 间 
的 关系 。 这 条 线 两 端的 符号 表明 关系 的 基数 。 在 roles.id 一 侧 的 短 坚 线 表示 “一 个 "， 而 
users.role_id 一 侧 的 符号 表示 “多 个 ”。 二 者 一 起 构成 一 对 多 关系 ， 即 roles 表 中 的 各 行 
可 以 对 应 于 user 表 中 的 多 行 。 

从 这 个 例子 可 以 看 出 ， 关 系 型 数据 库存 储 数据 很 高 效 ， 而 且 避 免 了 重复 。 将 这 个 数据 库 中 
的 用 户 角色 重 命名 也 很 简单 ， 因 为 角色 名 只 出 现在 一 个 地 方 。 一 旦 在 roles 表 中 修改 完 角 
色 名 ， 所 有 通过 role_id 引用 这 个 角色 的 用 户 就 都 能 立即 看 到 更 新 。 


但 从 另 一 方面 来 看 ， 把 数据 分 别 存放 在 多 个 表 中 还 是 很 复杂 的 。 生 成 一 个 包含 角色 的 用 户 
列表 会 遇 到 一 个 小 问题 ， 因 为 要 先 分 别 从 两 个 表 中 读 取 用 户 和 用 户 角色 ， 再 将 其 联结 起 
来 。 关 系 型 数据 库 引擎 为 联结 操作 提供 了 必要 的 文 持 。 


5.2 NoSQL 数 据 库 


所 有 不 符合 上 证 所 述 的 关系 模型 的 数据 库 统 称 为 NoSQL 数据 库 。NoSQL 数据 库 一 般 使 用 
集合 代替 表 ， 使 用 文档 代替 记录 。NoSQL 数据 库 采 用 的 设计 方式 使 联结 变 得 困难 ， 所 以 多 
数 根本 不 支持 这 种 操作 。 对 于 结构 如 图 5-1 所 示 的 NoSQL 数据 库 ， 若 要 列 出 各 用 户 及 其 
角色 ， 需 要 在 应 用 中 执行 联结 操作 ， 即 先 读 取 每 个 用 户 的 role_id， 再 在 roles 表 中 搜索 
对 应 的 记录 。 


NoSQL 数据 库 更 适合 设计 成 如 图 5-2 所 示 的 结构 。 这 是 执行 反 规 范 化 操作 得 到 的 结果 ， 它 
减少 了 表 的 数量 ， 却 增加 了 数据 重复 量 。 
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图 5-2: NoSQL 数据 库 示例 
这 种 结构 的 数据 库 要 把 角色 名 存储 在 每 个 用 户 中 。 如 此 一 来 ， 重 命名 角色 的 操作 就 变 得 很 
耗 时 ， 可 能 需要 更 新 大 量 文档 。 


使 用 NoSQL 数据 库 当 然 也 有 好 处 。 数 据 重复 可 以 提升 查询 速度 。 列 出 用 户 及 其 角色 的 操 
作 将 很 简单 ， 因 为 无 须 联结 。 
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5.3 使 用 SQL 还 是 NoSQL 


SQL 数据 库 擅 于 用 高 效 且 紧凑 的 形式 存储 结构 化 数据 。 这 种 数据 库 需 要 花费 大 量 精力 保证 
数据 的 一 致 性 ， 需 要 考虑 停电 或 硬件 失效 。 为 了 达到 这 种 程度 的 可 靠 性 ， 关 系 型 数据 库 
采用 一 种 称 为 ACID 的 范式 ， 即 atomicity (原子 性 ) 、consistency (一 致 性 ) 、isolation ( 隔 
离 性 ) 和 durability (持续 性 )。NoSQL 数据 库 放 宽 了 对 ACID 的 要 求 ， 从 而 获得 性 能 上 的 
优势 。 

对 不 同类 型 数据 库 的 全 面 分 析 和 对 比 超 出 了 本 书 范 畴 。 对 中 小 型 应 用 来 说 ，SQL 和 
NoSQL 数据 库 都 是 很 好 的 选择 ， 而 且 性 能 相当 。 


5.4 Python 数据 库 框 架 


大 多 数 数据 库 引擎 都 有 对 应 的 Python 包 ， 包 括 开源 包 和 商业 包 。Flask 并 不 限制 你 使 用 
何 种 类 型 的 数据 库 包 ， 因 此 你 可 以 根据 自己 的 喜好 选择 使 用 MySQL、Postgres、SQLite、 
Redis、MongoDB、CouchDB 或 DynamoDB。 


如 果 这 些 都 无 法 满足 需求 ， 还 有 一 些 数据 库 抽 象 层 代码 包 供 选 择 ， 例 如 SQLAlchemy 和 
MongoEngine。 你 可 以 使 用 这 些 抽象 包 直 接 处 理 高 等 级 的 Python 对 象 ， 而 不 用 处 理 如 表 、 
文档 或 查询 语言 之 类 的 数据 库 实体 。 
选择 数据 库 框 架 时 ， 要 考虑 很 多 因素 。 
易 用 性 
如 果 直 接 比 较 数据 库 引 敬 和 数据 库 抽象 层 ， 显 然后 者 取胜 。 抽 象 层 ， 也 称 为 对 象 关 系 映 
射 器 (ORM) 或 对 象 文 档 映 射 器 (ODM) ， 在 用 户 不 知 不 觉 的 情况 下 把 高 层 的 面向 对 
象 操 作 转 换 成 低层 的 数据 库 指令 。 
性 能 
ORM 和 ODM 把 对 象 业 务 转 换 成 数据 库 业 务 时 会 有 一 定 的 损耗 。 多 数 情况 下 ， 这 种 性 
能 的 降低 微不足道 ， 但 也 不 一 定 都 是 如 此 。 一 般 情 况 下 ，ORM 和 ODM 对 生产 率 的 提 
升 远 远 超 过 了 这 一 丁点 儿 的 性 能 降低 ， 所 以 性 能 降低 这 个 理由 不 足以 说 服用 户 完 全 放弃 
ORM 和 ODM。 真 正 的 关键 点 在 于 选择 一 个 能 直接 操作 低层 数据 库 的 抽象 层 ， 以 防 特 
定 的 操作 需要 直接 使 用 数据 库 原生 指令 优化 。 
可 移植 性 
选择 数据 库 时 ， 必 须 考 虑 其 是 否 能 在 你 的 开发 平台 和 生产 平台 中 使 用 。 例 如 ， 如 果 你 打 
算 利用 云 平台 托管 应 用 ， 就 要 知道 这 个 云 服务 提供 了 哪些 数据 库 可 供 选 择 。 
可 移植 性 还 针对 ORM 和 ODM。 尽 管 有 些 框 架 只 为 一 种 数据 库 引 敬 提 供 抽象 层 ， 但 其 
他 框架 可 能 做 了 更 高 层 的 抽象 ， 支 持 不 同 的 数据 库 引 擎 ， 而 且 都 使 用 相同 的 面向 对 象 接 
口 。SQLAlchemy ORM 就 是 一 个 很 好 的 例子 ， 它 支持 很 多 关系 型 数据 库 引 敬 ， 包 括 流 
行 的 MySQL、Postgres 和 SQLite。 

























































































































































































FLask 集成 度 


选择 数据 库 框架 时 ， 不 一 定 非得 选择 已 经 集成 了 Flask 的 框架 ， 但 选择 这 样 的 框架 可 以 
节省 编写 集成 代码 的 时 间 。 使 用 集成 了 Flask 的 框架 可 以 简化 配置 和 操作 ， 所 以 专门 为 
Flask 开发 的 扩展 是 你 的 首选 。 


基于 以 上 因素 ， 本 书 选 择 使 用 的 数据 库 框架 是 Flask-SQLAlchemy， 这 个 Flask 扩展 包装 
了 SQLAlchemy 框架 。 


5.5 使 用 Flask-SQLAIchemy 管 理 数据 库 


Flask-SQLAlchemy 是 一 个 Flask 扩展 ， 简 化 了 在 Flask 应 用 中 使 用 SQLAlchemy 的 操作 。 
SQLAlchemy 是 一 个 强大 的 关系 型 数据 库 框 架 ， 支 持 多 种 数据 库 后 台 。SQLAlchemy 提供 
了 高 层 ORM， 也 提供 了 使 用 数据 库 原生 SQL 的 低层 功能 。 
与 其 他 多 数 扩展 一 样 ，Flask-SQLAlchemy 也 使 用 pip 安装 : 


(venv) $ pip install fLask-sqLaLchemy 


在 Flask-SQLAlchemy 中 ， 数 据 库 使 用 URL 指定 。 几 种 最 流行 的 数据 库 引 擎 使 用 的 URL 
格式 如 表 5-1 所 示 。 


表 5-1: FLask-SQLAIchemy 数 据 库 URL 









































数据 库 引 擎 URL 

MySQL mysql://username:password@hostname/database 
Postgres postgresql://username:password@hostname/database 
SQLite (Linux, macOS) sqlite:////absolute/path/to/database 

SQLite (Windows) sqlite:///c:/absolute/path/to/database 


在 这 些 URL 中 ，hostname 表示 数据 库 服务 所 在 的 主机 ， 可 以 是 本 地 主机 (localhost)， 也 
可 以 是 远程 服务 器 。 数 据 库 服务 器 上 可 以 托管 多 个 数据 库 ， 因 此 database 表示 要 使 用 的 数 
据 库 名 。 如 果 数 据 库 需要 验证 身份 ， 使 用 username 和 password 提供 数据 库 用 户 的 凭据 。 


























SQLite 数据 库 没 有 服务 器 ， 因 此 不 用 指定 hostname、username 和 password。 
URL 中 的 database 是 磁盘 中 的 文件 名 。 





应 用 使 用 的 数据 库 URL 必须 保存 到 Flask 配置 对 象 的 SQLALCHEMY_DATABASE_URI 键 中 。 
Flask-SQLAlchemy 文档 还 建议 把 SQLALCHEMY_TRACK_MODIFICATIONS 键 设 为 False， 以 便 在 
不 需要 跟踪 对 象 变 化 时 降低 内 存 消耗 。 其 他 配置 选项 的 作用 参阅 Flask-SQLAlchemy 的 文 
档 。 示 例 5-1 展示 如 何 初 始 化 及 配置 一 个 简单 的 SQLite 数据 库 。 


示例 5-1 hello.py: 配置 数据 库 


import os 
from flask_sqlalchemy import SQLALchemy 
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basedir = os.path.abspath(os.path.dirname(__file _ )) 


app = Flask(__name_ ) 
app.config['SQLALCHEMY_DATABASE_URI'] =\ 

'sqlite:///' + os.path.join(basedir, 'data.sqlite') 
app.config['SQLALCHEMY_TRACK_MODIFICATIONS'] = False 


db = SQLALchemy(app) 


db 对 象 是 SQLALchemy 类 的 实例 ， 表 示 应 用 使 用 的 数据 库 ， 通 过 它 可 获得 Flask-SQLAIchemy 
提供 的 所 有 功能 。 


5.6 定义 模型 
模型 这 个 术语 表示 应 用 使 用 的 持久 化 实体 。 在 ORM 中 ， 模 型 一 般 是 一 个 Python 类 ， 类 中 
的 属性 对 应 于 数据 库 表 中 的 列 。 


Flask-SQLAlchemy 创建 的 数据 库 实例 为 模型 提供 了 一 个 基 类 以 及 一 系列 辅助 类 和 辅助 函 
数 ， 可 用 于 定义 模型 的 结构 。 图 5-1 中 的 roles 表 和 users 表 可 像 示 例 5-2 那样 ， 定 义 为 
Role 和 User 模型 。 






































示例 5-2 ”hello.py: 定义 Role 和 User 模型 


class Role(db.Model): 
_tablename = 'roles' 
id = db.Column(db.Integer, primary_key=True) 
name = db.Column(db.String(64), unique=True) 


def _ repr__(self): 
return '<Role %r>' % seLf.name 


class User(db.Model): 
_tablename _ = "Users' 
id = db.Column(db.Integer, primary_key=True) 
username = db.Column(db.String(64), unique=True, index=True) 


def _ repr__(self): 
return '<User %r>' % self.username 


类 变量 _tablename__ 定义 在 数据 库 中 使 用 的 表 名 。 如 果 没 有 定义 _tablename ，Flask- 
SQLAlchemy 会 使 用 一 个 默认 名 称 ， 但 默认 的 表 名 没有 遵守 流行 的 使 用 复数 命名 的 约定 ， 
所 以 最 好 由 我 们 自己 来 指定 表 名 。 其 余 的 类 变量 都 是 该 模型 的 属性 ， 定 义 为 db.Column 类 
的 实例 。 

db.Column 类 构造 函数 的 第 一 个 参数 是 数据 库 列 和 模型 属性 的 类 型 。 表 5-2 列 出 了 一 些 可 用 
的 列 类 型 以 及 在 模型 中 使 用 的 Python 类 型 。 


表 5-2: 最 常用 的 SQLAIchemy 列 类 型 















































类 型 名 Python 类 型 说 明 

Integer int 普通 整数 ， 通 常 是 32 位 
SmaLLInteger int 取 值 范围 小 的 整数 ， 通 常 是 16 位 
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类 型 名 Python 类 型 说 明 

BigInteger int 或 Long 不 限制 精度 的 整数 

FLoat float 浮 点 数 

Numeric decimal.Decimal 定点 数 

String str 变 长 字符 串 

Text str 变 长 字符 串 ， 对 较 长 或 不 限 长 度 的 字符 串 做 了 优化 

Unicode unicode 变 长 Unicode 字符 串 

UnicodeText unicode 变 长 Unicode 字符 串 ， 对 较 长 或 不 限 长 度 的 字符 串 
做 了 优化 

Boolean bool 布尔 值 

Date datetime.date 日 期 

Time datetime .time 时 间 

DateTime datetime.datetime 日 期 和 时 间 

Interval datetime. timedelta 时 间 间 隔 

Enum str 一 组 字符 串 

pickleType 任何 Python 对 象 自动 使 用 Pickle 序列 化 

LargeBinary str 二 进 制 blob 





db.Column 的 其 余 参 数 指定 属性 的 配置 选项 。 表 5-3 列 出 了 一 些 可 用 选项 。 
表 5-3: 最 常用 的 SQLAIchemy 列 选项 

















选项 名 说 明 

primary_key 如 果 设 为 True， 列 为 表 的 主键 

unique 如 果 设 为 True， 列 不 允许 出 现 重复 的 值 

index 如 果 设 为 True， 为 列 创建 索引 ， 提 升 查询 效率 

nullable 如 果 设 为 True， 列 允许 使 用 空 值 ， 如 果 设 为 Fatse， 列 不 允许 使 用 空 值 
default 为 列 定义 默认 值 


Flask-SQLAlchemy 要 求 每 个 模型 都 定义 主键 ， 这 一 列 经 常 命名 为 id。 





虽然 没有 强制 要 求 ， 但 这 两 个 模型 都 定义 了 __repr()__ 方法 ,返回 一 个 具有 可 读 性 的 字符 
串 表 示 模 型 ， 供 调试 和 测试 时 使 用 。 


5.7 关系 


关系 型 数据 库 使 用 关系 把 不 同 表 中 的 行 联系 起 来 。 图 5-1 所 示 的 关系 图 表示 用 户 和 角色 之 
间 的 一 种 简单 关系 。 这 是 角色 到 用 户 的 一 对 多 关系 ， 因 为 一 个 角色 可 属于 多 个 用 户 ， 而 每 
个 用 户 都 只 能 有 一 个 角色 。 
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5-1 中 的 一 对 多 关系 在 模型 类 中 的 表示 方法 如 示例 5-3 所 示 。 
示例 5-3: hello.py: 在 数据 库 模 型 中 定义 关系 


class Role(db.Model): 
# ... 
users = db.relationship('User', backref='role') 


class User(db.Model): 
# 


role_id = db.Column(db.Integer, db.ForeignKey('roles.id')) 


如 图 5-1 所 示 ， 关 系 使 用 users 表 中 的 外 键 连接 两 行 。 添 加 到 User 模型 中 的 role_id 列 被 
定义 为 外 键 ， 就 是 这 个 外 键 建立 起 了 关系 。 传 给 db.ForeignKey() 的 参数 'roles.id' 表明 ， 
这 列 的 值 是 roles 表 中 相应 行 的 id 值 。 


从 “一 ” 那 一 端 可 见 ， 添 加 到 Role 模型 中 的 users 属性 代表 这 个 关系 的 面向 对 象 视角 。 对 
于 一 个 Role 类 的 实例 ， 其 users 属性 将 返回 与 角色 相关 联 的 用 户 组 成 的 列表 〈( 即 “多 ”和 那 
一 端 )。db.relationship() 的 第 一 个 参数 表明 这 个 关系 的 另 一 端 是 哪个 模型 。 如 果 关 联 的 
模型 类 在 模块 后 面 定义 ， 可 使 用 字符 串 形式 指定 。 


db.relationship() 中 的 backref 参数 向 User 模型 中 添加 一 个 role 属性 ， 从 而 定义 反 向 关 
系 。 通 过 User 实例 的 这 个 属性 可 以 获取 对 应 的 Role 模型 对 象 ， 而 不 用 再 通过 role_id 外 
键 获取 。 

多 数 情况 下 ，db.relationship() 都 能 自行 找到 关系 中 的 外 键 ， 但 有 时 却 无 法 确定 哪 一 列 是 
外 键 。 例 如 ， 如 果 User 模型 中 有 两 个 或 以 上 的 列 定 义 为 Rote 模型 的 外 键 ，SQLAlchemy 
就 不 知道 该 使 用 哪 一 列 。 如 果 无 法 确定 外 键 ， 就 要 为 db.relationship() 提供 额外 的 参数 。 
表 5-4 列 出 了 定义 关系 时 常用 的 配置 选项 。 


表 5-4: 常用 的 SQLAIchemy 关 系 选项 















































选项 名 说 明 

backref 在 关系 的 另 一 个 模型 中 添加 反 向 引用 

primaryjoin 明确 指定 两 个 模型 之 间 使 用 的 联结 条 件 ， 只 在 模棱两可 的 关系 中 需要 指定 

lazy 指定 如 何 加 载 相关 记录 ， 可 选 值 有 select (首次 访问 时 按 需 加 载 )、immediate ( 源 对 象 





加 载 后 就 加 载 )、joined (加 载 记录 ， 但 使 用 联结 )、subquery (立即 加 载 ， 但 使 用 子 查 
询 )，noload ( 永 不 加 载 ) 和 dynamic (不 加 载 记录 ， 但 提供 加 载 记 录 的 查询 ) 




















uselist 如 果 设 为 False， 不 使 用 列表 ， 而 使 用 标量 值 
order_by 指定 关系 中 记录 的 排序 方式 
secondary 指定 多 对 多 关系 中 关联 表 的 名 称 


secondaryjoin ”SQLAIchemy 无 法 自行 决定 时 ， 指 定 多 对 多 关系 中 的 二 级 联结 条 件 








如 果 你 从 GitHub 上 克隆 了 这 个 应 用 的 Git 仓库 ， 那 么 可 以 执行 git checkout 
5a 检 出 应 用 的 这 个 版 本 。 





除了 一 对 多 之 外 ， 还 有 其 他 几 种 关系 类 型 。 一 对 一 关系 可 以 用 前 面 介绍 的 一 对 多 关系 表 
示 ， 但 调用 db.relationship() 时 要 把 useList 设 为 FaLse， 把 “多 ” 变 成 “一 ”。 多 对 一 
关系 也 可 使 用 一 对 多 表示 ， 对 调 两 个 表 即 可 ,或 者 把 外 键 和 db.relationship() 都 放 在 
“多 ”这 一 侧 。 最 复杂 的 关系 类 型 是 多 对 多 ， 需 要 用 到 第 三 张 表 ， 这 个 表 称 为 关联 表 (或 
联结 表 ) 。 多 对 多 关系 在 第 12 章 讨论 。 


5.8 ”数据 库 操作 


现在 模型 已 经 按照 图 5-1 所 示 的 数据 库 关系 图 完成 配置 ， 可 以 随时 使 用 了 。 学 习 使 用 模型 
的 最 好 方法 是 在 Python shell 中 实际 操作 。 接 下 来 的 几 节 将 介绍 最 常用 的 数据 库 操作 。shell 
使 用 flask shell 命令 启动 。 不 过 在 执行 这 个 命令 之 前 ， 要 按照 第 2 章 的 说 明 ， 把 FLASK_ 
APP 环境 变量 设 为 hello.py。 


5.8.1 创建 表 


首先 ， 要 让 Flask-SQLAlchemy 根据 模型 类 创建 数据 库 。db.create_all() 函数 将 寻找 所 有 
db.Model 的 子 类 ， 然 后 在 数据 库 中 创建 对 应 的 表 : 
(venv) $ flask shell 


>>> from hello import db 
>>> db.create_all() 


现在 查看 应 用 目录 ， 你 会 发 现 有 个 名 为 datasqlite 的 文件 ， 文 件 名 与 配置 中 指定 的 一 样 。 
如 果 数 据 库 表 已 经 存在 于 数据 库 中 ， 那 么 db.create_all() 不 会 重新 创建 或 者 更 新 相应 的 
表 。 如 果 修改 模型 后 要 把 改动 应 用 到 现 有 的 数据 库 中 ， 这 一 行为 会 带 来 不 便 。 更 新 现 有 数 
据 库 表 的 蛮 力 方式 是 先 删 除 旧 表 再 重新 创建 : 


>>> db.drop_all() 
>>> db.create_all() 


遗憾 的 是 ， 这 个 方法 有 个 我 们 不 想 看 到 的 副作用 ， 它 把 数据 库 中 原 有 的 数据 都 销毁 了 。 本 
章 末 尾 将 介绍 一 种 更 好 的 数据 库 更 新 方式 。 


5.8.2 插入 行 
下 面 这 上段 代码 创建 一 些 角 色 和 用 户 : 


>>> from hello import Role, User 

>>> admin_role = Role(name="'Admin') 

>>> mod_role = Role(name="'Moderator') 

>>> User_role = Role(name='User') 

>>> user_john = User(username=' john' ，roLe=admin_roLe) 
>>> User_susan = User(username='susan', role=user_role) 
>>> User_david = User(username='david', role=user_role) 


模型 的 构造 函数 接受 的 参数 是 使 用 关键 字 参 数 指定 的 模型 属性 初始 值 。 注 意 ，role 属性 
也 可 使 用 ， 虽然 它 不 是 真正 的 数据 库 列 ， 但 却 是 一 对 多 关系 的 高 级 表示 。 新 建 对 象 时 没有 
明确 设 定 id 属性 ， 因 为 在 多 数 数据 库 中 主键 由 数据 库 自身 管理 。 现 在 这 些 对 象 只 存在 于 
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Python 中 ， 还 未 写 和 数据库。 因此 ，id 尚未 赋值 : 


>>> print(admin_role.id) 
None 

>>> print(mod_role.id) 
None 

>>> print(user_role.id) 
None 


对 数据 库 的 改动 通过 数据 库 会 话 管理 ， 在 Flask-SQLAlchemy 中 ， 会 话 由 db.session 表示 。 
准备 把 对 象 写 入 数据 库 之 前 ， 要 先 将 其 添加 到 会 话 中 : 


>>> db.session.add(admin_role) 
>>> db.session.add(mod_role) 
>>> db.session.add(user_role) 
>>> db.session.add(user_john) 
>>> db.session.add(user_susan) 
>>> db.session.add(user_david) 


或 者 简写 成 : 


>>> db.session.add_all([admin_role, mod_role, user_role, 
user_john, user_susan, user_david]) 


为 了 把 对 象 写 和 数据库， 我 们 要 调用 commit() 方法 提交 会 话 : 
>>> db.session.commit() 

提交 数据 后 再 查看 id 属性 ， 现 在 它们 已 经 赋值 了 : 
>>> print(admin_role.id) 
> print(mod_role.id) 


>>> print(user_role.id) 
3 














数据 库 会 话 db.session 和 第 4 章 介 绍 的 Flask session 对 象 没 有 关系 。 数 据 
库 会 话 也 称 为 事务 。 


数据 库 会 话 能 保证 数据 库 的 一 臻 性。 提交 操作 使 用 原子 方式 把 会 话 中 的 对 象 全 部 写 入 数据 
库 。 如 果 在 写 入 会 话 的 过 程 中 发 生 了 错误 ， 那 么 整个 会 话 都 会 失效 。 如 果 你 始终 把 相关 改 
动 放 在 会 话 中 提交 ， 就 能 避免 因 部 分 更 新 导致 的 数据 库 不 一 致 。 








数据 库 会 话 也 可 回 滚 。 调 用 db.session.rollback() 后 ， 添 加 到 数据 库 会 话 
中 的 所 有 对 象 都 将 还 原 到 它们 在 数据 库 中 的 状态 。 








5.8.3 修改 行 
在 数据 库 会 话 上 调用 add() 方法 也 能 更 新 模型 。 我 们 继续 在 之 前 的 shell 会 话 中 进行 操作 ， 
下 面 这 个 例子 把 "Admin" 角色 重 命名 为 "Administrator": 


>>> admin_role.name = 'Administrator' 
>>> db.session.add(admin_role) 
>>> db.session.commit() 


5.8.4 删除 行 
数据 库 会 话 还 有 个 detete() 方法 。 下 面 这 个 例子 把 "Moderator" 角色 从 数据 库 中 删除 : 


>>> db.session.delete(mod_role) 
>>> db.session.commit() 


注意 ， 删 除 与 插入 和 更 新 一 样 ， 提 交 数 据 库 会 话 后 才 会 执行 。 
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5.8.5 查询 行 


Flask-SQLAlchemy 为 每 个 模型 类 都 提供 了 query 对 象 。 最 基本 的 模型 查询 是 使 用 aLL( ) 方 
法 取 回 对 应 表 中 的 所 有 记录 : 

>>> Role.query.all() 

[<Role 'Administrator'>, <Role 'User'>] 

>>> User .query.all() 

[<User 'john'>, <User 'susan'>, <User 'david'>] 
使 用 过 滤器 可 以 配置 query 对 象 进行 更 精确 的 数据 库 查 询 。 下 面 这 个 例子 查找 角色 为 
"User" 的 所 有 用 户 : 


>>> User .query.filter_by(role=user_role).all() 
[<User 'susan'>, <User 'david'>] 


若 想 查看 SQLAlchemy 为 查询 生成 的 原生 SQL 查询 语句 ， 只 需 把 query 对 象 转换 成 字 
符 串 : 
>>> str(User .query.filter_by(role=user_role)) 


"SELECT Users.id AS users_id, users.username AS users_uysername, 
Users.role id AS users_role id NnFROM Users \NWHERE :param 1 = users.role_id' 


如 果 你 退出 了 shell 会 话 ， 前 面 这 些 例子 中 创建 的 对 象 就 不 会 以 Python 对 象 的 形式 存在 ， 
但 在 数据 库 表 中 仍 有 对 应 的 行 。 如 果 打 开 一 个 新 的 shell 会 话 ， 要 从 数据 库 中 读 取 行 ， 重 新 
创建 Python 对 象 。 下 面 这 个 例子 发 起 一 个 查询 ， 加 载 名 为 "User" 的 用 户 角 色 : 
>>> User_role = Role.query.filter_by(name="'User').first() 

注意 ， 这 里 发 起 查询 的 不 是 al1() 方法 ， 而 是 first() 方法 。al1() 方法 返回 所 有 结果 构成 
的 列表 ， 而 first() 方法 只 返回 第 一 个 结果 ， 如 果 没 有 结果 的 话 ， 则 返回 None。 因 此 ， 如 
果 知 道 查询 最 多 返回 一 个 结果 ， 就 可 以 用 这 个 方法 。 

filter_by() 等 过 滤器 在 query 对 象 上 调用 ， 返 回 一 个 更 精确 的 query 对 象 。 多 个 过 滤器 可 
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以 一 起 调用 ， 直 到 获得 所 需 结 果 。 


表 5-5 列 出 了 可 在 query 对 象 上 调用 的 常用 过 滤器 。 完 整 的 列表 参见 SQLAlchemy 文档 
(http:/docs.sqlalchemy.org ) 。 


表 5-5: 常用 的 SQLAlchemy 查 询 过 滤器 




































































过 滤器 说 明 

filter() 把 过 滤器 添加 到 原 查 询 上 ， 返 回 一 个 新 查询 

filter_by() 把 等 值 过 滤器 添加 到 原 查 询 上 ， 返 回 一 个 新 查询 

Limit() 使 用 指定 的 值 限 制 原 查 询 返 回 的 结果 数量 ， 返 回 一 个 新 查询 
offset() 偏 移 原 查询 返回 的 结果 ， 返 回 一 个 新 查询 

order_by() 根据 指定 条 件 对 原 查 询 结 果 进行 排序 ， 返 回 一 个 新 查询 
group_by() 根据 指定 条 件 对 原 查 询 结 果 进 行 分 组 ， 返 回 一 个 新 查询 





























在 查询 上 应 用 指定 的 过 滤器 后 ， 调 用 at1() 方法 将 执行 查询 ， 以 列表 的 形式 返回 结果 。 除 
了 al1() 方法 之 外 ， 还 有 其 他 方法 能 触发 查询 执行 。 表 5-6 列 出 了 执行 查询 的 其 他 方法 。 


表 5-6: 最 常用 的 SQLAIchemy 查 询 执 行 方法 


































































































A 说 明 

alL() 以 列表 形式 返回 查询 的 所 有 结果 

first() 返回 查询 的 第 一 个 结果 ， 如 果 没 有 结果 ， 则 返回 None 

first_or_404() 返回 查询 的 第 一 个 结果 ， 如 果 没 有 结果 ， 则 终止 请 求 ， 返 回 404 错误 响应 

get() 返回 指定 主键 对 应 的 行 ， 如 果 没 有 对 应 的 行 ， 则 返回 None 

get_or_404() 返回 指定 主键 对 应 的 行 ， 如 果 没 找到 指定 的 主键 ， 则 终止 请 求 ， 返 回 404 错误 响应 
count() 返回 查询 结果 的 数量 

paginate() 返回 一 个 Paginate 对 象 ， 包 含 指定 范围 内 的 结果 





























关系 与 查询 的 处 理 方式 类 似 。 下 面 这 个 例子 分 别 从 关系 的 两 端 查询 角色 和 用 户 之 间 的 一 对 
多 关系 : 


>>> Users = User_role.users 

>>> Users 

[<User 'susan'>, <User 'david'>] 
>>> users[0].role 

<Role 'User'> 


这 个 例子 中 的 user_role.users 查询 有 个 小 问题 。 执 行 user_role.users 表达 式 时 ， 隐 式 的 查 
询 会 调用 alt() 方法 ， 返 回 一 个 用 户 列 表 。 此 时 ，query 对 象 是 隐藏 的 ， 无 法 指定 更 精确 的 
查询 过 滤器 。 就 这 个 示例 而 言 ， 返 回 一 个 按照 字母 顺序 排列 的 用 户 列 表 可 能 更 好 。 在 示例 
5-4 中 ， 我 们 修改 了 关系 的 设置 ， 加 入 了 lazy='dynamic' 参数 ， 从 而 禁止 自动 执行 查询 。 


示例 5-4: hello.py: 动态 数据 库 关 系 
class Role(db.Model): 
村 
users = db.relationship('User', backref='role', lazy='dynamic') 























邮 


这 样 配置 关系 之 后 ，user_role.users 将 返回 一 个 尚未 执行 的 查询 ， 因 此 可 以 在 其 上 添加 过 
滤器 : 





>>> User_role.users.order_by(User .username).all() 
[<User 'david'>, <User 'susan'>] 

>>> User_role.users.count() 

2 


5.9 在 视图 函数 中 操作 数据 库 


前 一 市 介绍 的 数据 库 操作 可 以 直接 在 视图 函数 中 进行 。 示 例 5-5 是 首页 路 由 的 新 版 本 ， 把 


月 











日 户 输入 的 名 字 记 录 到 数据 库 中 。 





示例 5-5 hello.py: 在 视图 函数 中 操作 数据 库 








@app.route('/', methods=['GET', 'POST']) 
def index(): 
form = NameForm() 
if form.validate on_submit(): 
User = User.query.filter_by(username=form.name.data).first() 
if user is None: 
User = User(username=form.name.data) 
db.session.add(user) 
db.session.commit() 
session['known'] = False 
else: 
session['known'] = True 
session['name'] = form.name.data 
form.name.data = ' 
return redirect(url_for('index')) 
return render_template('index.html', 
form=form, name=session.get('name'), 
known=session.get('known', False)) 





在 这 个 修改 后 的 版 本 中 ， 提 交 表 单 后 ， 应 用 会 使 用 filter_by() 查询 过 滤器 在 数据 库 中 查 
找 提交 的 名 字 。 变 量 known 被 写 入 用 户 会 话 中 ， 因 此 重 定向 之 后 ， 可 以 把 数据 传 给 模板 ， 








月 


有 于 显示 自 定义 的 欢迎 消息 。 注 意 ， 为 了 让 应 用 正常 运行 ， 必 须 按 照 前 面 介绍 的 方法 ,在 





Python shell 中 创建 数据 库 表 。 


对 应 的 模板 新 版 本 如 示例 5-6 所 示 。 这 个 模板 使 用 known 参数 在 欢迎 消息 中 加 入 了 第 二 行 ， 
从 而 对 已 知 用 户 和 新 用 户 显示 不 同 的 内 容 。 


示例 5-6 templates/index.html:; 在 模板 中 定制 欢迎 消息 





{% extends "base.html" %} 
{% import "bootstrap/wtf.html" as wtf %} 


{% block title %}Flasky{% endblock %} 


{% block page_content %} 

<div class="page-header"> 
<hi>Hello, {% if name %}{{ name }}{% else %}Stranger{% endif %}!</h1> 
{% if not known %} 
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<p>PLeased to meet you!</p> 
{% else %} 
<p>Happy to see you again!</p> 
{% endif %} 
</div> 
{{ wtf.quick_form(form) }} 
{% endblock %} 


如 果 你 从 GitHub 上 克隆 了 这 个 应 用 的 Git 仓库 ， 那 么 可 以 执行 git checkout 
5b 检 出 应 用 的 这 个 版 本 。 





5.10 集成 Python shell 


每 次 启动 shell 会 话 都 要 导 人 数据 库 实 例 和 模型 ， 这 真是 份 枯燥 的 工作 。 为 了 避免 一 直 重 复 
导入 ， 我 们 可 以 做 些 配置 ， 让 flask shell 命令 自动 导入 这 些 对 象 。 


若 想 把 对 象 添 加 到 导入 列表 中 ， 必 须 使 用 app.sheLL_context_processor 装饰 器 创建 并 注册 
一 个 shell 上 下 文 处 理 器 ， 如 示例 5-7 所 示 。 


示例 5-7 ”hello.py: 添加 一 个 shell 上 下 文 
@app.shell_context_processor 
def make_shell_context(): 
return dict(db=db, User=User, Role=Role) 


这 个 shell 上 下 文 处 理 器 函数 返回 一 个 字典 ， 包 含 数 据 库 实例 和 模型 。 除 了 默认 导入 的 app 
之 外 ，flask shell 命令 将 自动 把 这 些 对 象 导入 shell。 


$ flask shell 

>>> app 

<Flask 'hello'> 

>>> db 

<SQLALchemy engine='sqlite:////home/flask/flasky/data.sqlite'> 
>>> User 

<class 'hello.User'> 





如 果 你 从 GitHub 上 克隆 了 这 个 应 用 的 Git 仓库 ， 那 么 可 以 执行 git checkout 
5c 检 出 应 用 的 这 个 版 本 。 





5.11 使 用 Flask-Migrate 实 现 数据 库 迁 移 


在 开发 应 用 的 过 程 中 ， 你 会 发 现 有 时 需要 修改 数据 库 模 型 ， 而 且 修 改 之 后 还 要 更 新 数据 
库 。 仅 当 数 据 库 表 不 存在 时 ，Flask-SQLAlchemy 才 会 根据 模型 创建 。 因 此 ， 更 新 表 的 唯 
方式 就 是 先 删 除 旧 表 ， 但 是 这 样 做 会 丢失 数据 库 中 的 全 部 数据 。 
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更 新 表 更 好 的 方法 是 使 用 数据 库 迁 移 框架 。 源 码 版 本 控制 工具 可 以 跟踪 源码 文件 的 变化 ， 
类 似 地 ， 数 据 库 迁 移 框架 能 跟踪 数据 库 模式 的 变化 ， 然 后 以 增 量 的 方式 把 变化 应 用 到 数据 
库 中 。 


SQLAlchemy 的 开发 人 员 编 写 了 一 个 迁移 框架 ， 名 为 Alembic。 除 了 直接 使 用 Alembic 之 
外 ，Flask 应 用 还 可 使 用 Flask-Migrate 扩展 。 这 个 扩展 是 对 Alembic 的 轻 量 级 包装 ， 并 与 
flask 命令 做 了 集成 。 


5.11.1 创建 迁移 仓库 


首先 ， 要 在 虚拟 环境 中 安装 Flask-Migrate: 


(venv) $ pip install flask-migrate 
这 个 扩展 的 初始 化 方法 如 示例 5-8 所 示 。 
示例 5-8: hello.py: 初始 化 Flask-Migrate 


from flask_migrate import Migrate 


























Hi 
migrate = Migrate(app, db) 


为 了 开放 数据 库 迁 移 相 关 的 命令 ，Flask-Migrate 添加 了 flask db 命令 和 几 个 子 命令 。 在 新 
项 目 中 可 以 使 用 init 子 命令 添加 数据 库 迁 移 支 持 : 


(venv) $ flask db init 
Creating directory /home/flask/flasky/migrations...done 
Creating directory /home/flask/flasky/migrations/versions...done 
Generating /home/flask/flasky/migrations/alembic.ini...done 
Generating /home/flask/flasky/migrations/env.py...done 
Generating /home/flask/flasky/migrations/env.pyc...done 
Generating /home/fLask/fLasky/migrations/README. . .done 
Generating /home/flask/flasky/migrations/script.py.mako...done 
Please edit configuration/connection/logging settings in 
'/home/flask/flasky/migrations/alembic.ini' before proceeding. 


这 个 命令 会 创建 migrations 目录 ， 所 有 迁移 脚本 都 存放 在 这 里 。 如 果 你 是 通过 git checkout 
检 出 示例 项 目的 ， 那 么 无 须 做 这 一 步 ， 因 为 GitHub 仓库 中 已 有 迁移 仓库 。 























数据 库 迁 移 仓库 中 的 文件 要 和 应 用 的 其 他 文件 一 起 纳入 版 本 控制 。 





5.11.2 ”创建 迁移 脚本 


在 Alembic 中 ， 数 据 库 迁 移 用 迁移 脚本 表示 。 脚 本 中 有 两 个 国 数 ， 分 别 是 upgrade() 和 
downgrade()。upgrade() 国 数 把 迁移 中 的 改动 应 用 到 数据 库 中 ，downgrade() 函数 则 将 改动 
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删除 。Alembic 具有 添加 和 删除 改动 的 


能 力 ， 意 味 着 数据 库 可 重 设 到 修改 历史 的 任意 一 点 。 





我 们 可 以 使 用 revision 命令 手动 创建 Alembic 迁移 ， 也 可 使 用 migrate 命令 自动 创建 。 
手动 创建 的 迁移 只 是 一 个 骨架 ，upgrade() 和 downgrade() 函数 都 是 空 的 ， 开 发 者 要 使 用 
Alembic 提供 的 Operations 对 象 指令 实 现 具体 操作 。 自 动 创建 的 迁移 会 根据 模型 定义 和 数 
据 库 当前 状态 之 间 的 差异 尝试 生成 upgrade() 和 downgrade() 函数 的 内 容 。 














列 。 如 果 原 封 不 动 地 使 用 























自动 创建 的 迁移 不 一 定 总 是 正确 的 ， 有 可 能 会 漏 掉 一 些 细节 。 比 如 说 我 们 重 
命名 了 一 列 ， 自 动 生成 的 迁移 可 能 会 把 这 当 作 删 除了 一 列 ， 然 后 又 新 增 了 一 




















自动 生成 的 迁移 ， 这 一 列 中 的 数据 就 会 丢失 ! 鉴于 





此 ， 自 动 生成 迁移 脚本 后 一 定 要 进行 检查 ， 把 不 准确 的 部 分 手动 改过 来 。 





使 用 Flask-Migrate 管理 数据 库 模 式 变化 的 步骤 如 下 。 





(1) 对 模型 类 做 必要 的 修改 。 


(2) 执行 flask db migrate 命令 ， 自 动 创建 一 个 迁移 脚本 。 
(3) 检查 自动 生成 的 脚本 ， 根 据 对 模型 的 实际 改动 进行 调整 。 








(4) 把 迁移 脚本 纳入 版 本 控制 。 


(5) 执行 flask db upgrade 命令 ， 把 迁移 应 用 到 数据 库 中 。 
flask db migrate 子 命令 用 于 自动 创建 迁移 脚本 : 


(venv) $ flask db migrate -m "initial migration" 
INFO [alembic.migration] Context impl SQLiteImpl. 
INFO [alembic.migration] Will assume non-transactional DDL. 
INFO [alembic.autogenerate] Detected added table 'roles' 
INFO [alembic.autogenerate] Detected added table 'users' 
INFO [alembic.autogenerate.compare] Detected added index 
'ix_users_username' on '['username']' 

Generating /home/flask/flasky/migrations/versions/i1bc 





594146bb5_initial_migration.py 


...done 


如 果 你 一 直 使 用 git checkout 命令 检 出 示例 应 用 ， 那 么 无 须 执行 migrate 命令 ， 因 为 相应 


的 Git 标签 中 都 有 迁移 脚本 。 


如 果 你 从 GitHub 上 克隆 了 这 个 应 用 的 Git 仓库 ， 那 么 可 以 执行 git checkout 
5d 检 出 应 用 的 这 个 版 本 。 注 意 ， 你 无 须 再 为 这 个 应 用 生成 迁移 仓库 和 迁移 脚 








本 





5.11.3 更 新 数据 库 

















因为 GitHub 仓库 中 已 经 有 了 。 


检查 并 修正 好 迁移 脚本 之 后 ， 执 行 flask db upgrade 命令 ， 把 迁移 应 用 到 数据 库 中 : 


(venv) $ flask db upgrade 


INFO [alembic.migration] Context impl SQLiteImpl. 
INFO [alembic.migration] Will assume non-transactional DDL. 
INFO [alembic.migration] Running upgrade None -> 1bc594146bb5, initial migration 





对 第 一 个 迁移 来 说 ， 其 作用 与 调用 db.create_all() 方法 一 样 。 但 在 后 续 的 迁移 中 ，flask 
db upgrade 命令 能 把 改动 应 用 到 数据 库 中 ， 且 不 影响 其 中 保存 的 数据 。 


如 果 你 按照 之 前 的 说 明 操 作 过 ， 那 么 已 经 使 用 db.create_all() 函数 创建 了 
数据 库 文件 。 此 时 ，flask db upgrade 命令 将 失败 ， 因 为 它 试图 创建 已 经 存 
在 的 数据 库 表 。 一 种 简单 的 处 理 方法 是 ， 把 data.sqlite 数据 库 文件 删 掉 ， 然 
后 执行 flask db upgrade 命令 ， 通 过 迁移 框架 重新 创建 数据 库 。 另 一 种 方法 
是 不 执行 flask db upgrade 命令 ， 而 是 使 用 flask db stamp 命令 把 现 有 数据 
库 标 记 为 已 更 新 。 















































5.11.4 添加 几 个 迁移 


在 开发 项 目的 过 程 中 ， 时 常 要 修改 数据 库 模 型 。 如 果 使 用 迁移 框架 管理 数据 库 ， 必 须 在 
迁移 脚本 中 定义 所 有 改动 ， 否 则 改动 将 不 可 复 现 。 修 改 数据 库 的 步骤 与 创建 第 一 个 迁移 
类 似 。 


(1) 对 数据 库 模 型 做 必要 的 修改 。 

(2) 执行 flask db migrate 命令 ， 生 成 迁移 脚本 。 

(3) 检查 自动 生成 的 脚本 ， 改 正 不 准确 的 地 方 。 

(4) 执行 flask db upgrade 命令 ， 把 改动 应 用 到 数据 库 中 。 


实现 一 个 功能 时 ， 可 能 要 多 次 修改 数据 库 模 型 才能 得 到 预期 结果 。 如 果 前 一 个 迁移 还 未 提 
交 到 源码 控制 系统 中 ， 可 以 继续 在 那个 迁移 中 修改 ， 以 免 创建 大 量 无 意义 的 小 迁移 脚本 。 
在 前 一 个 迁移 脚本 的 基础 上 修改 的 步骤 如 下 。 


(1) 执 行 flask db downgrade 命令 ,还 原 前 一 个 脚本 对 数据 库 的 改动 (注意 ， 这 可 能 导致 
部 分 数据 丢失 )。 

(2) 删除 前 一 个 迁移 脚本 ， 因 为 现在 已 经 没什么 用 了 。 

(3) 执 行 fLask db migrate 命令 生成 一 个 新 的 数据 库 迁 移 脚 本 。 这 个 迁移 脚本 除了 前 面 删 
除 的 那个 脚本 中 的 改动 之 外 ， 还 包括 这 一 次 对 模型 的 改动 。 

(4) 根据 前 面 的 说 明 ， 检 查 并 应 用 迁移 脚本 。 















































与 数据 库 迁 移 相 关 的 其 他 子 命令 参见 Flask-Migrate 文档 (https://flask-migrate. 


readthedocs.io/) 。 


数据 库 设计 和 用 法 相关 的 话题 十 分 重要 ， 有 大 量 相关 的 图 书 。 本 章 只 是 简介 ， 后 续 章 节 将 
讨论 更 高 级 的 话题 。 下 一 章 着 重 说 明 电子 邮件 发 送 。 
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第 6 章 


电子 邮件 








很 多 类 型 的 应 用 都 需要 在 特定 事件 发 生 时 通知 用 户 ， 而 常用 的 通信 方法 是 电子 邮件 。 本 章 
介绍 如 何在 Flask 应 用 中 发 送 电 子 邮件 。 


使 用 Flask-Mail 提 供电 子 邮件 支持 


虽然 Python 标准 库 中 的 smtplib 包 可 用 于 在 Flask 应 用 中 发 送 电子 邮件 ， 但 包装 了 smtplib 
的 Flask-Mail 扩展 能 更 好 地 与 Flask 集成 。Flask-Mail 使 用 pip 安装 : 


(venv) $ pip install flask-mail 








Flask-Mail 连接 到 简单 邮件 传输 协议 (SMTP，simple mail transfer protocol) 服务 器 ， 把 邮 
件 交 给 这 个 服务 器 发 送 。 如 果 不 进行 配置 ， 则 Flask-Mail 连接 localhost 上 的 25 端口 ， 无 
须 验 证 身份 即 可 发 送 电 子 邮件 。 表 6-1 列 出 了 可 用 来 设置 SMTP 服务 器 的 配置 。 


表 6-1: Flask-Mail SMTP 服 务 器 的 配置 






























































本 置 默认 信 说明 
MAIL_SERVER localhost 包子 邮件 服务 器 的 主机 名 或 卫 地 址 

MAIL_PORT 25 电子 邮件 服务 器 的 端 

MAIL_USE_TLS False 启用 传输 层 安 全 (TLS，transport layer security) 协议 
NMAIL_USE_SSL False 启用 安全 套 接 层 (SSL，secure sockets layer) 协议 
MAIL_USERNAME None 邮件 账户 的 用 户 名 

MAIL_PASSWORD None 邮件 账户 的 密码 








在 开发 过 程 中 ， 连 接 到 外 部 SMTP 服务 器 可 能 更 方便 。 举 个 例子 ， 示 例 6-1 展示 了 如 何 配 
置 应 用 ， 以 便 使 用 Google Gmail 账户 发 送 电 子 邮 件 。 
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示例 6-1 hello.py: 配置 Flask-Mail 使 用 Gmail 


import os 

# ... 

app.config['MAIL_SERVER'] = 'smtp.googlemail.com' 
app.config['MAIL_PORT'] = 587 

app.config['MAIL_USE_TLS'] = True 

app.config['MAIL_USERNAME'] = os.environ.get('MAIL_USERNAME') 
app.config['MAIL_PASSWORD'] = os.environ.get('MAIL_PASSWORD') 


千 万 不 要 把 账户 凭据 直接 写 入 脚本 ， 特 别 是 当 你 计划 开源 自己 的 作品 时 。 为 
了 保护 账户 信息 ， 脚 本 应 该 从 环境 变量 中 导入 敏感 信息 。 








基于 安全 方面 的 考虑 ，Gmail 账户 要 求 外 部 应 用 连接 电子 邮件 服务 器 时 使 用 
OAnuth2 验证 身份 。 然 而 ，Python 的 smtplib 库 不 支持 这 种 身份 验证 方法 。 
为 了 能 以 标准 的 SMTP 身份 验证 方法 使 用 Gmail 账户， 打开 Google 账户 设 
置 页 面 ， 在 左边 的 菜单 栏 里 点 击 “Signing in to Google”。 在 打开 的 页 面 中 找 
到 “Allow less secure apps” 设 置 并 勾 选 上 。 如 果 你 对 这 样 设置 自己 的 Gmail 
账户 不 放心 ， 可 以 注册 一 个 二 级 账户 ， 专 门 用 于 测试 电子 邮件 发 送 。 









































Flask-Mail 的 初始 化 方法 如 示例 6-2 所 示 。 


示例 6-2 hello.py: 初始 化 Flask-Mail 


from flask_mail import Mail 
mail = Mail(app) 


保存 电子 邮件 服务 器 用 户 名 和 密码 的 两 个 环境 变量 要 在 环境 中 定义 。 如 果 你 使 用 的 是 
Linux 或 macOS， 可 以 按照 下 面 的 方式 设 定 这 两 个 变量 : 


(venv) $ export MAIL_USERNAME=<Gmail username> 
(venv) $ export MAIL_PASSWORD=<Gmail password> 


微软 Windows 用 户 可 按照 下 面 的 方式 设 定 环 境 变量 : 


(venv) $ set MAIL_USERNAME=<Gmail username> 
(venv) $ set MAIL_PASSWORD=<Gmail password> 


在 Python shell 中 发 送 电 子 邮件 


你 可 以 打开 一 个 shell 会 话 ， 发 送 一 封 测试 邮件 ， 检 查 配 置 是 否 正确 (记得 把 you@example. 
conm 换 成 你 自己 的 电子 邮件 地 址 ) : 


(venv) $ flask shell 

>>> from flask_mail import Message 

>>> from hello import mail 

>>> msg = Message('test email', sender='you@example.com', 
5 recipients=['youQexampLe.com']) 

>>> msg.body = 'This is the plain text body' 
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>>> msg.htmL = 'This is the <b>HTML</b> body' 
>>> with app.app_context(): 
mail.send(msg) 


注意 ，Flask-Mail 的 send() 函数 使 用 current_app， 因 此 要 在 激活 的 应 用 上 下 文中 执行 。 


在 应 用 中 集成 电子 邮件 发 送 功 能 

为 了 避免 每 次 都 手动 编写 电子 邮件 消息 ， 我 们 最 好 把 应 用 发 送 电子 邮件 的 通用 部 分 抽象 出 
来 ， 定 义 成 一 个 函数 。 这 么 做 还 有 个 好 处 ， 即 该 函数 可 以 使 用 Jinja2 模板 泻 染 邮件 正文 ， 
灵活 性 极 高 。 有 具体 实现 如 示例 6-3 所 示 。 

示例 6-3 hello.py: 电子 邮件 支持 


from flask_mail import Message 























app.config['FLASKY_MAIL_SUBJECT_PREFIX'] = '[FLasky]' 
app.config['FLASKY_MAIL_SENDER'] = "FLasky Admin <fLaskyQexampLe.com>' 


def send email(to, subject, template, **kwargs): 
msg = Message(app.config['FLASKY_MAIL_SUBJECT_PREFIX'] + subject, 
sender=app.config['FLASKY_MAIL_SENDER'], recipients=[to]) 
msg.body = render_template(template + '.txt', **kwargs) 
msg.html = render_tempLate(tempLate + '.html', **kwargs) 
mail.send(msg) 


这 个 函数 用 到 了 两 个 应 用 层面 的 配置 项 ,分别 定 义 邮 件 主 题 的 前 缀 和 发 件 人 的 地 址 。send_ 
email() 函数 的 参数 分 别 为 收 件 人 地 址 、 主 题 、 泻 染 邮 件 正 文 的 模板 和 关键 字 参 数列 表 。 
指定 模板 时 不 能 包含 扩展 名 ,这样 才 能 使 用 两 个 模板 分 别 泻 染 纯 文本 正文 和 HTML 正文 。 
调用 者 传 入 的 关键 字 参 数 将 传 给 render_template() 函数 ， 作 为 模板 变量 提供 给 模板 使 用 ， 
用 于 生成 电子 邮件 正文 。 


我 们 可 以 轻松 扩展 index() 视图 函数 ， 每 当 表 单 接收 到 新 的 名 字 ， 应 用 就 给 管理 员 发 送 一 
封 电子 邮件 。 修 改 方法 如 示例 6-4 所 示 。 


示例 6-4 hello.py: 电子 邮件 示例 
es 
app.config['FLASKY_ADMIN'] = os.environ.get('FLASKY_ADMIN') 
类 
@app.route('/', methods=['GET', 'POST']) 
def index(): 
form = NameForm() 
if form.validate on_submit(): 
User = User.query.filter_by(username=form.name.data).first() 
if user is None: 
User = User(username=form.name.data) 
db.session.add(user) 
session['known'] = False 
if app.config['FLASKY_ADMIN']: 
send_email(app.config['FLASKY_ADMIN'], 'New User ' ， 
'mail/new_user', user=user) 
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session['known'] = True 
session['name'] = form.name.data 
form.name.data = ' 
return redirect(url_for('index')) 
return render_template('index.html', form=form, name=session.get('name'), 
known=session.get('known', False)) 


电子 邮件 的 收 件 人 保存 在 环境 变量 FLASKY_ADMIN 中 ， 在 应 用 启动 过 程 中 ， 它 会 加 载 到 一 个 
同名 配置 变量 中 。 我 们 要 创建 两 个 模板 文件 ， 分 别 用 于 泻 染 纯 文本 和 HTML 版 本 的 邮件 正 
文 。 这 两 个 模板 文件 都 保存 在 templates 目录 下 的 mail 子 目录 中 ， 以 便 和 普通 模板 区 分 开 
来 。 电 子 邮 件 的 模板 中 有 一 个 模板 参数 是 用 户 ， 因 此 调用 send_email() 函数 时 要 以 关键 字 
参数 的 形式 传 和 用户。 














如 果 你 从 GitHub 上 克隆 了 这 个 应 用 的 Git 仓库 ， 那 么 可 以 执行 git checkout 
6a 检 出 应 用 的 这 个 版 本 。 

















除了 前 面 提 到 的 环境 变量 MAIL_USERNAME 和 MAIL_PASSWORD 之 外 ， 应 用 的 这 个 版 本 还 需要 使 
用 环境 变量 FLASKY_ADMIN。Linux 和 macOS 用 户 可 使 用 下 面 的 命令 设置 这 个 变量 : 


(venv) $ export FLASKY_ADMIN=<your-email-address> 
对 微软 Windows 用 户 来 说 ， 等 价 的 命令 是 : 
(venv) $ set FLASKY_ADMIN=<your-email-address> 


设置 好 这 些 环境 变量 后 ， 我 们 就 可 以 测试 应 用 了 。 每 次 你 在 表单 中 填写 新 名 字 ， 管 理 员 都 
会 收 到 一 封 电子 邮件 。 


异步 发 送 电子 邮件 

如 果 你 发 送 了 几 封 测试 邮件 ， 可 能 会 注意 到 mail.send() 函数 在 发 送 电 子 邮 件 时 停 庶 了 几 
秒 钟 ， 在 这 个 过 程 中 浏览 器 就 像 无 响应 一 样 。 为 了 在 处 理 请 求 过 程 中 避免 不 必要 的 延迟 ， 
我 们 可 以 把 发 送 电 子 邮 件 的 函数 移 到 后 台 线 程 中 。 修 改 方法 如 示例 6-5 所 示 。 


示例 6-5 hello.py: 异步 发 送 电 子 邮件 


from threading import Thread 





























def send_async_email(app, msg): 
with app.app_context(): 
mail.send(msg) 


def send email(to, subject, template, **kwargs): 
msg = Message(app.config['FLASKY_MAIL_SUBJECT_PREFIX'] + subject, 
sender=app.config['FLASKY_MAIL_SENDER'], recipients=[to]) 
msg.body = render_template(template + '.txt', **kwargs) 
msg.html = render_template(template + '.html', **kwargs) 
thr = Thread(target=send_async_email, args=[app, msg]) 
thr.start() 
return thr 





电子 邮件 | 63 


上 述 实现 涉及 一 个 有 趣 的 问题 。 很 多 Flask 扩展 都 假设 已 经 存在 激活 的 应 用 上 下 文 和 (或 ) 
请 求 上 下 文 。 前 面 说 过 ，Flask-Mail 的 send() 函数 使 用 current_app， 因 此 必须 激活 应 用 
上 下 文 。 不 过 ， 上 下 文 是 与 线程 配套 的 ， 在 不 同 的 线程 中 执行 mail.send() 函数 时 ， 要 使 
用 app.app_context() 人 工 创建 应 用 上 下 文 。app 实例 作为 参数 传人 线程 ， 因 此 可 以 通过 它 
来 创建 上 下 文 。 














如 果 你 从 GitHub 上 克隆 了 这 个 应 用 的 Git 仓库 ， 可 以 执行 git checkout 6b 
检 出 应 用 的 这 个 版 本 。 











现在 再 运行 应 用 ， 你 会 发 现 应 用 流畅 多 了 。 不 过 要 注意 ， 应 用 要 发 送 大 量 电 子 邮件 时 ， 使 
用 专门 发 送 电 子 邮件 的 作业 要 比 给 每 封 邮件 都 新 建 一 个 线程 更 合适 。 例 如 ， 我 们 可 以 把 执 
行 send_async_email() 函数 的 操作 发 给 Celery 任务 队列 。 


至 此 ， 我 们 完成 了 对 大 多 数 Web 应 用 所 需 功 能 的 概述 。 现 在 的 问题 是 ，hello.py 脚本 变 得 
越 来 越 大 ， 难 以 维护 。 在 下 一 章 中 ， 你 将 学 到 如 何 组 织 大 型 应 用 的 结构 。 
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大 型 应 用 的 结构 





尊 





尽管 在 单个 脚本 文件 中 编写 小 型 Web 应 用 很 方便 ， 但 这 种 方法 的 伸缩 性 不 好 。 应 用 变 复杂 
后 ， 使 用 单个 大 型 源码 文件 会 导致 很 多 问题 。 


不 同 于 多 数 其 他 的 Web 框架 ，Flask 并 不 强制 要 求 大 型 项 目 使 用 特定 的 组 织 方式 ， 应 用 结 
构 的 组 织 方 式 完 全 由 开发 者 决定 。 本 章 将 介绍 一 种 使 用 包 和 模块 组 织 大 型 应 用 的 方式 。 本 
书后 续 示 例 都 将 采用 这 种 结构 。 


7.1 项 目 结构 
Flask 应 用 的 基本 结构 如 示例 7-1 所 示 。 


示例 7-1 多 文件 Flask 应 用 的 基本 结构 
| -fLasky 
| -app/ 
-templates/ 
-static/ 
-main/ 
|-_init .py 
-errors.py 
-forms.py 
-Views.py 
-__init .py 
-email.py 
-models.py 
|-migrations/ 
| -tests/ 
|-_init .py 
|-test*.py 
|-venv/ 
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| -requtrements .txXt 
| -config.py 
| -fLasky.py 


这 种 结构 有 4 个 顶级 文件 夹 : 





。 Flask 应 用 一 般 保存 在 名 为 app 的 包 中 ， 


。 和 之 前 一 样 ， 数 据 库 迁 移 脚本 在 
。 单元 测试 在 tests 包 中 编写 ; 


。 和 之 前 一 样 ，Python 虚拟 环境 在 





此 外 ， 这 种 结构 还 多 了 一 些 新 文件 : 


migrations 文件 夹 中 ， 


venv 文件 夹 中 。 


。 requirements.txt 列 出 了 所 有 依赖 包 ， 便 于 在 其 他 计算 机 中 重新 生成 相同 的 虚拟 环境 ; 


。 config.py 存储 配置 ， 





。 flasky.py 定义 Flask 应 用 实例 ， 同 时 还 有 一 些 辅助 管理 应 用 的 任务 。 








为 了 帮助 你 完全 理解 这 个 结构 ， 下 本 





i 几 节 会 说 明 把 hello.py 应 用 转换 成 这 种 结构 的 过 程 。 











7.2 配置 选项 





应 用 经 常 需要 设 定 多 个 配置 。 这 方 





面 最 好 的 例子 就 是 开发 、 测 试 和 生产 环境 要 使 用 不 同 的 











数据 库 ， 这 样 才 不 会 彼此 影响 。 





除了 hello.py 中 类 似 字 典 的 app.config 对 象 之 外 ， 还 可 以 使 用 具有 层次 结构 的 配置 类 。 
config.py 文件 的 内 容 如 示例 7-2 所 示 ， 洒 盖 hello.py 中 的 所 有 设置 。 


示例 7-2 config.py: 应 用 的 配置 


import os 


basedir = os.path.abspath(os.path.dirname(__file _)) 


class Config: 


SECRET_KEY = os.environ.get('SECRET_KEY') or "hard to guess string' 

MAIL_SERVER = os.environ.get('MAIL_SERVER' ，'smtp.googLemaiL.com') 

MAIL_PORT = int(os.environ.get('MAIL PORT', '587')) 

MAIL_USE_TLS = os.environ.get('MAIL_ USE TLS', 'true').lower() in \ 
['true'’, 'on', '1'] 

MAIL_USERNAME = os.environ.get('MAIL USERNAME') 

MAIL_PASSWORD = os.environ.get('MAIL PASSWORD') 

FLASKY_MAIL SUBJECT_PREFIX = '[FLasky]' 

FLASKY_MAIL_SENDER = 'Flasky Admin <fLaskyQexampLe.com>' 

FLASKY_ADMIN = os.environ.get('FLASKY_ADMIN') 

SQLALCHEMY_TRACK_MODIFICATIONS = False 


@staticmethod 
def init_app(app): 
pass 


class DevelopmentConfig(Config): 


DEBUG = True 
SQLALCHEMY_DATABASE_URI = os.environ.get('DEV_DATABASE_ URL') or \ 
'sqlite:///' + os.path.join(basedir, 'data-dev.sqlite') 
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class TestingConfig(Config): 
TESTING = True 
SQLALCHEMY_DATABASE_URI = os.environ.get('TEST_DATABASE_URL') or \ 
'sqlite://' 


class ProductionConfig(Config): 
SQLALCHEMY_DATABASE_URI = os.environ.get('DATABASE URL') or \ 
'sqlite:///' + os.path.join(basedir, 'data.sqlite') 


config = { 
'development': DevelopmentConfig, 
'testing': TestingConfig， 
'production': ProductionConfig, 


'default': DeveLopmentConfig 


} 


基 类 Config 中 包含 通用 配置 ， 各 个 子 类 分 别 定义 专用 的 配置 。 如 果 需 要 ， 你 还 可 添加 其 他 
配置 类 。 


为 了 让 配置 方式 更 灵活 且 更 安全 ， 多 数 配 置 都 可 以 从 环境 变量 中 导入 。 例 如 ，SECRET_KEY 
的 值 ， 这 是 个 敏感 信息 ， 可 以 在 环境 中 设 定 ， 但 系统 也 提供 了 一 个 默认 值 ， 以 防 环境 中 没 
有 定义 。 通 常 ， 在 开发 过 程 中 可 以 使 用 这 些 设置 的 默认 值 ， 但 是 在 生产 服务 器 中 应 该 通过 
环境 变量 设 定 各 个 值 。 电 子 邮 件 服 务 器 的 配置 选项 也 都 从 环境 变量 中 导入 ， 不 过 为 了 开发 
方便 ， 提 供 了 指向 Gmail 服务 器 的 默认 值 。 























千 万 不 要 把 密码 或 其 他 机 密 信息 写 在 纳入 版 本 控制 的 配置 文件 中 。 








在 3 个 子 类 中 ，SQLALCHEMY_DATABASE_URI 变量 都 被 指定 了 不 同 的 值 。 这 样 应 用 就 可 以 在 不 
同 的 环境 中 使 用 不 同 的 数据 库 。 把 不 同 环境 的 数据 库 区 分 开 是 十 分 必要 的 ， 因 为 你 青 定 不 
想 让 单元 测试 修改 日 常 开发 中 使 用 的 数据 库 。 各 配置 子 类 尝试 从 环境 变量 中 导入 数据 库 的 
URL， 如 果 相 应 的 环境 变量 没有 设 定 ， 则 使 用 基于 SQLite 的 默认 值 。 测 试 环境 默认 使 用 一 
个 内 存 中 的 数据 库 ， 因 为 测试 运行 结束 后 无 需 保 留任 何 数 据 。 


开发 环境 和 生产 环境 都 配置 了 邮件 服务 器 。 为 了 再 给 应 用 提供 一 种 定制 配置 的 方式 ， 
Config 类 及 其 子 类 可 以 定义 init_app() 类 方法 ， 其 参数 为 应 用 实例 。 现 在 ， 基 类 Config 
中 的 init_app() 方法 为 空 。 
在 这 个 配置 脚本 末尾 ，config 字典 中 注册 了 不 同 的 配置 环境 ， 而 且 还 注册 了 一 个 默认 配置 
(这 里 注册 为 开发 环境 ) 。 


7.3 ”应 用 包 


应 用 包 用 于 存放 应 用 的 所 有 代码 、 模 板 和 静态 文件 。 我 们 可 以 把 这 个 包 直接 称 为 app (应 
用 )， 如 果 有 需求， 也 可 使 用 一 个 应 用 专属 的 名 称 。templates 和 static 目录 现在 是 应 用 包 
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的 一 部 分 ， 因 此 要 把 二 者 移 到 app 包 中 。 数 据 库 模型 和 电子 邮件 支持 函数 也 要 移 到 这 个 包 
中 ， 分 别 保存 为 app/models.py 和 app/email.py。 


7.3.1 使 用 应 用 工厂 函数 


在 单个 文件 中 开发 应 用 是 很 方便 ， 但 却 有 个 很 大 的 缺点 : 应 用 在 全 局 作用 域 中 创建 ， 无 法 
动态 修改 配置 。 运 行 脚本 时 ， 应 用 实例 已 经 创建 ， 再 修改 配置 为 时 已 晚 。 这 一 点 对 单元 测 
试 尤其 重要 ， 因 为 有 时 为 了 提高 测试 覆盖 度 ， 必 须 在 不 同 的 配置 下 运行 应 用 。 


这 个 问题 的 解决 方法 是 延迟 创建 应 用 实例 ， 把 创建 过 程 移 到 可 显 式 调用 的 工厂 函数 中 。 这 
种 方法 不 仅 可 以 给 脚本 留 出 配置 应 用 的 时 间 ， 还 能 够 创建 多 个 应 用 实例 ， 为 测试 提供 便 
利 。 应 用 的 工厂 函数 在 app 包 的 构造 文件 中 定义 ， 如 示例 7-3 所 示 。 


示例 7-3 app/_init _.py: 应 用 包 的 构造 文件 
from flask import Flask, render_template 
from flask_bootstrap import Bootstrap 
from flask_mail import Mail 
from flask_moment import Moment 
from flask_sqlalchemy import SQLALchemy 
from config import config 
































bootstrap = Bootstrap() 
mail = Mail() 

moment = Moment() 

db = SQLALchemy() 


def create_app(config_name): 
app = Flask(__name_ ) 
app.config.from object(config[config_name]) 
config[config_ name].init_app(app) 


bootstrap.init_app(app) 
mail.init_app(app) 
moment.init_app(app) 
db.init_app(app) 

















# 添加 路 由 和 自 定义 的 错误 页 
return app 


构造 文件 导入 了 大 多 数 正 在 使 用 的 Flask 扩展 。 由 于 尚未 初始 化 所 需 的 应 用 实例 ， 所 以 创 
建 扩展 类 时 没有 向 构造 函数 传人 参数 ， 因 此 扩展 并 未 真正 初始 化 。create_app() 函数 是 应 
用 的 工厂 函数 ， 接 受 一 个 参数 ， 是 应 用 使 用 的 配置 名 。 配 置 类 在 config.py 文件 中 定义 ， 其 
中 保存 的 配置 可 以 使 用 Flask app.config 配置 对 象 提供 的 from_object() 方法 直接 导入 应 
用 。 至 于 配置 对 象 ， 则 可 以 通过 名 称 从 config 字典 中 选择 。 应 用 创建 并 配置 好 后 ， 就 能 初 
始 化 扩展 了 。 在 之 前 创建 的 扩展 对 象 上 调用 init_app() 便 可 以 完成 初始 化 。 


现在 ， 应 用 在 这 个 工厂 函数 中 初始 化 ， 使 用 Flask 配置 对 象 的 from_object() 方法 ， 其 参数 
为 config.py 中 定义 的 某 个 配置 类 。 此 外 ， 这 里 还 调用 了 所 选 配置 的 init_app() 方法 ， 以 
便 执 行 更 复杂 的 初始 化 过 程 。 
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工厂 函数 返回 创建 的 应 用 示例 ， 不 过 要 注意 ， 现 在 工厂 国 数 创建 的 应 用 还 不 完整 ， 因 为 没 
有 路 由 和 自 定义 的 错误 页 面 处 理 程序 。 这 是 下 一 市 要 讲 的 话题 。 


7.3.2 在 蓝本 中 实现 应 用 功能 


转换 成 应 用 工厂 函数 的 操作 让 定义 路 由 变 复杂 了 。 在 单 脚本 应 用 中 ， 应 用 实例 存在 于 全 局 
作用 域 中 ， 路 由 可 以 直接 使 用 app.route 装饰 器 定义 。 但 现在 应 用 在 运行 时 创建 ， 只 有 调用 
create_app() 之 后 才能 使 用 app.route 装饰 器 ， 这 时 定义 路 由 就 太 晚 了 。 自 定义 的 错误 页 下 
处 理 程序 也 面临 相同 的 问题 ， 因 为 错误 页 面 处 理 程序 使 用 app.errorhandter 装饰 器 定义 。 


幸好 ，Flask 使 用 蓝本 (blueprint) 提供 了 更 好 的 解决 方法 。 蓝 本 和 应 用 类 似 ， 也 可 以 定义 
路 由 和 错误 处 理 程序 。 不 同 的 是 ， 在 蓝本 中 定义 的 路 由 和 错误 处 理 程序 处 于 休眠 状态 ， 直 
到 蓝本 注册 到 应 用 上 之 后 ， 它 们 才 真 正成 为 应 用 的 一 部 分 。 使 用 位 于 全 局 作用 域 中 的 蓝本 
时 ， 定 义 路 由 和 错误 处 理 程序 的 方法 几乎 与 单 脚 本 应 用 一 样 。 


与 应 用 一 样 ， 蓝 本 可 以 在 单个 文件 中 定义 ， 也 可 使 用 更 结构 化 的 方式 在 包 中 的 多 个 模块 中 
创建 。 为 了 获得 最 大 的 灵活 性 ， 我 们 将 在 应 用 包 中 创建 一 个 子 包 ， 用 于 保存 应 用 的 第 一 个 
蓝本 。 示 例 7-4 是 这 个 子 包 的 构造 文件 ， 蓝 本 就 创建 于 此 。 


示例 7-4 app/main/_init .py: 创建 主 蓝 本 
from flask import Blueprint 











































































































main = Blueprint('main', __name_ ) 
from . import views, errors 


蓝本 通过 实例 化 一 个 Blueprint 类 对 象 创建 。 这 个 构造 函数 有 两 个 必须 指定 的 参数 ， 蓝 
本 的 名 称 和 蓝本 所 在 的 包 或 模块 。 与 应 用 一 样 ， 多 数 情况 下 第 二 个 参数 使 用 Python 的 


name__ 变量 即 可 。 


应 用 的 路 由 保存 在 包 里 的 app/main/views.py 模块 中 ， 而 错误 处 理 程序 保存 在 app/main/ 
errors.py 模块 中 。 导 入 这 两 个 模块 就 能 把 路 由 和 错误 处 理 程序 与 蓝本 关联 起 来 。 注 意 ， 这 
些 模块 在 app/main/_init_.py 脚本 的 末尾 导入 ， 这 是 为 了 避免 循环 导入 依赖 ， 因 为 在 app/ 
main/views.py 和 app/main/errors.py 中 还 要 导入 main 蓝本 ， 所 以 除非 循环 引用 出 现在 定义 
main 之 后 ， 否 则 会 致使 导入 出 错 。 


from .import <some-module> 句法 表示 相对 导入 。 语 句 中 的 . 表示 当前 包 。 稍 
后 还 会 见 到 一 种 十 分 有 用 的 相对 导入 句法 ， 即 from .. import <some-moduLe>， 
这 里 的 .. 表示 当前 包 的 上 一 层 。 




















蓝本 在 工厂 函数 create_app() 中 注册 到 应 用 上 ， 如 示例 7-5 所 示 。 


示例 7-5 app/_init .py: 注册 主 蓝 本 
def create_app(config_name): 
六 ea 
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from .main import main as main_blueprint 
app.register_blueprint(main_blueprint) 


return app 
示例 7-6 给 出 错误 处 理 程序 。 
示例 7-6 app/main/errors.py: 主 蓝 本 中 的 错误 处 理 程序 


from flask import render_template 
from . import main 








@main.app_errorhandler(404) 
def page_not_ found(e): 
return render_template('404.html'), 404 


@main.app_errorhandler(500) 
def internal_server_error(e): 
return render_template('500.html'), 500 


在 蓝本 中 编写 错误 处 理 程序 稍 有 不 同 ， 如 果 使 用 errorhandler 装饰 器 ， 那 么 只 有 蓝本 中 的 
错误 才能 触发 处 理 程序 。 要 想 注 册 应 用 全 局 的 错误 处 理 程序 ， 必 须 使 用 app_errorhandler 
装饰 器 。 

在 蓝本 中 定义 的 应 用 路 由 如 示例 7-7 所 示 。 

示例 7-7 app/main/views.py: 主 监 本 中 定义 的 应 用 路 由 


from datetime import datetime 

from flask import render_template, session, redirect, url_for 
from . import main 

from .forms import NameForm 

from .. import db 

from ..modeLs import User 



































@main.route('/', methods=['GET', 'POST']) 
def index(): 
form = NameForm() 
if form.validate on_submit(): 
ss 
return redirect(url_for('.index')) 
return render_template('index.html', 
form=form, name=session.get('name'), 
known=session.get('known', False), 
current time=datetime.utcnow()) 


在 蓝本 中 编写 视图 函数 主要 有 两 点 不 同 : 第 一 ， 与 前 面 的 错误 处 理 程序 一 样 ， 路 由 装饰 器 
由 蓝本 提供 ， 因 此 使 用 的 是 main.route， 而 非 app.route; 第 二 ，url_for() 函数 的 用 法 
不 同 。 你 可 能 还 记得 ，url_for() 函数 的 第 一 个 参数 是 路 由 的 端点 名 ， 在 应 用 的 路 由 中 ， 
默认 为 视图 函数 的 名 称 。 例 如 ， 在 单 脚本 应 用 中 ，index() 视图 函数 的 URL 可 使 用 urt_ 
for('index') 获取 。 

在 蓝本 中 就 不 一 样 了 ，Flask 会 为 蓝本 中 的 全 部 端点 加 上 一 个 命名 空间 ， 这 样 就 可 以 在 
不 同 的 蓝本 中 使 用 相同 的 端点 名 定义 视图 函数 ， 而 不 产生 冲突 。 命 名 空间 是 蓝本 的 名 称 





















































(BLueprint 构造 函数 的 第 一 个 参数 ) ， 而 且 它 与 端点 名 之 间 以 一 个 点 号 分 隔 。 因 此 ， 视 图 
函数 index() 注册 的 端点 名 是 main.index， 其 URL 使 用 urL_for('main.index' ) 获取 。 
url_for() 函数 还 支持 一 种 简写 的 端点 形式 ， 在 蓝本 中 可 以 省 略 蓝本 名 ， 例 如 urL_for 
(' .index' )。 在 这 种 写法 中 ， 使 用 当前 请 求 的 蓝本 名 补足 端点 名 。 这 意味 着 ， 同 一 蓝本 中 
的 重 定向 可 以 使 用 简写 形式 ， 但 跨 监 本 的 重 定向 必须 使 用 带 有 蓝本 名 的 完全 限定 端点 名 。 


为 了 完成 对 应 用 包 的 修改 ， 还 要 把 表单 对 象 移 到 蓝本 中 ， 保 存在 app/main/forms.py 模块 里 。 


7.4 应 用 脚本 


应 用 实例 在 顶级 目录 中 的 flasky.py 模块 里 定义 。 这 个 脚本 的 内 容 如 示例 7-8 所 示 。 
示例 7-8 flasky.py: 主 脚本 


import os 

from app import create_app，db 
from app.modeLs import User, Role 
from flask_migrate import Migrate 








app = create_app(os.getenv('FLASK_CONFIG') or 'default') 
migrate = Migrate(app, db) 


@app.shell_context_processor 
def make_shell_context(): 
return dict(db=db, User=User, Role=Role) 


这 个 脚本 先 创建 一 个 应 用 实例 。 如 果 已 经 定义 了 环境 变量 FLASK_CONFIG， 则 从 中 读 取 配置 
名 ; 否则 使 用 默认 配置 。 然 后 初始 化 Flask-Migrate 和 为 Python shell 定义 的 上 下 文 。 


因为 应 用 的 主 脚本 由 hello.py 变 成 了 flasky.py， 所 以 要 相应 地 修改 FLASK_APP 环境 变量 ， 
以 便 flLask 命令 找到 应 用 实例 。 此 外 ， 还 可 以 设置 FLASK_DEBUG=1， 启 用 Flask 的 调试 模 
式 。Linux 和 macOS 用 户 这 样 做 : 


(venv) $ export FLASK_APP=fLasky.py 
(venv) $ export FLASK_DEBUG=1 


微软 Windows 用 户 这 样 做 : 


(venv) $ set FLASK_APP=fLasky.py 
(venv) $ set FLASK_DEBUG=1 


7.5 ”需求 文件 


应 用 中 最 好 有 个 requirements.txt 文件 ， en ne i 如 果 要 在 
另 一 台 计 算 机 上 重新 生成 虚拟 环境 ， 这 个 文件 的 重要 性 就 体现 出 来 了 ， 例 如 部 署 应 用 时 使 
用 的 设备 。 这 个 文件 可 由 pip 自 使 用 的 命令 如 下 : 


(venv) $ pip freeze >requirements.txt 
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安装 或 升级 包 后 ， 最 好 更 新 这 个 文件 。 需 求 文件 的 内 容 示 例如 下 : 


alembic==0.9.3 
blinker==1.4 
click==6.7 
dominate==2.3.1 
Flask==0.12.2 
Flask-Bootstrap==3.3.7.1 
Flask-Mail==0.9.1 
Flask-Migrate==2.0.4 
FLask-Moment==0.5.1 
FLask-SQLALchemy==2.2 
Flask-WTF==0.14.2 
itsdangerous==0.24 
Jinja2==2.9.6 
Mako==1.0.7 
MarkupSafe==1.0 
python-dateutil==2.6.1 
python-editor==1.0.3 
six==1.10.0 
SQLALchemy==1.1.11 
visitor==0.1.3 
Werkzeug==0.12.2 
WTForms==2.1 


如 果 你 想 创建 这 个 虚拟 环境 的 完整 副本 ， 先 创建 一 个 新 的 虚拟 环境 ， 然 后 在 其 中 运行 下 述 














(venv) $ pip install -r requirements.txt 


当 你 阅读 本 书 时 ， 该 示例 requirements.txt 文件 中 的 版 本 号 可 能 已 经 过 期 了 。 如 果 愿 意 ， 你 
可 以 尝试 使 用 这 些 包 的 最 新 版 。 如 果 遇 到 问题 ， 可 以 随时 换 回 这 个 需求 文件 中 的 版 本 ， 攻 
为 这 些 版 本 与 本 书 开发 的 这 个 应 用 是 兼容 的 。 


7.6 单元 测试 


这 个 应 用 很 小 ， 没 什么 可 测试 的 。 不 过 为 了 演示 ， 我 们 可 以 编写 两 个 简单 的 测试 ， 如 示例 
7-9 所 示 。 















































示例 7-9 ”tests/test_basics.py: 单元 测试 


import unittest 
from flask import current_app 
from app import create app, db 


class BasicsTestCase(unittest.TestCase): 
def setUp(self): 
self.app = create_app('testing ') 
seLf .app_context = self.app.app_context() 
seLf .app_context.push() 
db.create_alLL() 


def tearDown(self): 
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db.session.remove() 
db.drop_all() 
self.app_context.pop() 


def test app_exists(self): 
self.assertFalse(current _ app is None) 


def test app_is testing(self): 
self.assertTrue(current_app.config['TESTING']) 


这 些 测试 使 用 Python 标准 库 中 的 unittest 包 编 写 。 测 试用 例 类 的 setup() 和 tearDown() 
方法 分 别 在 各 测试 之 前 和 之 后 运行 。 名 称 以 test_ 开头 的 方法 都 作为 测试 运行 。 





如 果 你 想 进 一 步 了 解 如 何 使 用 Python 的 unittest 包 编 写 测试 ， 请 阅读 官方 
文档 (https://docs.python.org/3.6/library/unittest.html) 。 





setUp() 方法 尝试 创建 一 个 测试 环境 ， 尽 量 与 正常 运行 应 用 所 需 的 环境 一 致 。 首 先 ， 使 用 
测试 配置 创建 应 用 ， 然 后 激活 上 下 文 。 这 一 步 的 作用 是 确保 能 在 测试 中 使 用 current_app， 
就 像 普通 请 求 一 样 。 然 后 ， 使 用 Flask-SQLAlchemy 的 create_all() 方法 创建 一 个 全 新 的 
数据 库 ， 供 测试 使 用 。 数 据 库 和 应 用 上 下 文 在 tearDown( ) 方法 中 删除 。 
第 一 个 测试 确保 应 用 实例 存在 。 第 二 个 测试 确保 应 用 在 测试 配置 中 运行 。 若 想 把 tests 目录 
作为 包 来 使 用 ， 要 添加 tests/init.py 模块 ， 不 过 这 个 文件 可 以 为 空 ， 因 为 unittest 包 会 扫 
描 所 有 模块 ， 找 出 测试 。 

如 果 你 从 GitHub 上 克隆 了 这 个 应 用 的 Git 仓库 ， 那 么 可 以 执行 git checkout 

7a 检 出 应 用 的 这 个 版 本 。 为 确保 安装 了 所 有 依赖 包 ， 还 需 执行 pip iinstall 


-Fr requirements.txt 命令 。 



































为 了 运行 单元 测试 ， 可 以 在 flasky.py 脚本 中 添加 一 个 自 定 义 命 令 。 示 例 7-10 展示 如 何 添 
加 test 命令 。 


示例 7-10 flasky.py: 启动 单元 测试 的 命令 
@app.cli.command() 
def test(): 
"”" "Run the unit tests.""" 
import unittest 
tests = unittest.TestLoader().discover('tests') 
unittest.TextTestRunner(verbosity=2).run(tests) 


app.ctt.conmand 装饰 器 把 自 定义 命令 变 得 很 简单 。 被 装饰 的 函数 名 就 是 命令 名 ， 函 数 的 文 
档 字符 串 会 显示 在 帮助 消息 中 。test() 函数 的 定义 体 中 调用 了 unittest 包 提供 的 测试 运行 
程序 。 


单元 测试 可 使 用 下 面 的 命令 运行 : 
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(venv) $ flask test 
test_app_exists (test basics.BasicsTestCase) ... ok 
test_app_is_testing (test_basics.BasicsTestCase) ... ok 


Ran 2 tests in 0.001s 


OK 


7.7 创建 数据 库 


重组 后 的 应 用 和 单 脚 本 版 本 使 用 不 同 的 数据 库 。 
首选 从 环境 变量 中 读 取 数据 库 的 URL， 同 时 还 提供 了 一 个 默认 的 SQLite 数据 库 作 为 备用 。 
3 种 配置 环境 中 的 环境 变量 名 和 SQLite 数据 库 文件 名 都 不 一 样 。 例 如 ， 在 开发 环境 中 ， 数 
据 库 URL 从 环境 变量 DEV_DATABASE_URL 中 读 取 ， 如 果 没 有 定义 这 个 环境 变量 ， 则 使 用 名 
为 data-dev.sqlite 的 SQLite 数据 库 。 
不 管 从 哪里 获取 数据 库 URL， 都 要 在 新 数据 库 中 创建 数据 表 。 如 果 使 用 Flask-Migrate 跟 
踪 迁 移 ， 可 使 用 下 述 命令 创建 数据 表 或 者 升级 到 最 新 修订 版 本 
(venv) $ flask db upgrade 


7.8 运行 应 用 


重 构 至 此 结束 ， 可 以 启动 应 用 了 。 先 确保 你 按照 7.4 节 的 说 明 更 新 了 FLASK_APP 环境 变量 ， 
然后 像 之 前 一 样 运行 应 用 : 
(venv) $ flask run 


每 次 启动 一 个 新 的 命令 提示 符 会 话 ， 都 要 设 定 FLASK_APP 和 FLASK_DEBUG 环境 变量 ， 这 有 
点 麻烦 。 你 可 以 做 些 配 置 ， 让 系统 自动 设 定 这 些 变量 。 如 果 你 使 用 bash， 可 以 把 环境 变量 
添加 到 ~/.bashrc 文件 中 。 

你 可 能 不 相信 ， 第 一 部 分 到 此 就 结束 了 。 现 在 你 已 经 学 到 了 使 用 Flask 开发 Web 应 用 的 必 
备 基础 知识 ， 不 过 可 能 还 不 确定 如 何 把 这 些 知识 融 贯 起 来 开发 一 个 真正 的 应 用 。 本 书 第 二 
部 分 的 目的 就 是 解决 这 个 问题 ， 我 将 带领 你 一 步 步 开发 出 一 个 完整 的 应 用 。 
















































































第 二 部 分 





实例 ， 社 区 博客 应 用 


第 8 和 章 


用 尸身 份 验 证 





多 数 应 用 都 要 记录 用 户 是 谁 。 用 户 连 接应 用 时 会 验证 身份 ， 通 过 这 一 过 程 ， 让 应 用 知道 自 
己 的 身份 。 应 用 知道 用 户 是 谁 后 ， 就 能 提供 有 针对 性 的 体验 。 

最 常用 的 身份 验证 方法 要 求 用 户 提供 一 个 身份 证 明 ， 可 以 是 用 户 的 电子 邮件 地 址 ， 也 可 以 
是 用 户 名 ， 以 及 一 个 只 有 用 户 自己 知道 的 密令 ， 我 们 称 之 为 密码 。 本 章 将 为 Flasky 开发 一 
个 完整 的 身份 验证 系统 。 


8.1 ”Flask 的 身份 验证 扩展 


优秀 的 Python 身份 验证 包 很 多 ， 但 没有 一 个 能 实现 所 有 功能 。 本 章 介绍 的 身份 验证 方案 将 
使 用 多 个 包 ， 而 且 还 要 编写 胶水 代码 ， 让 不 同 的 包 良 好 协作 。 本 章 使 用 的 包 及 其 作用 列表 
如 下 。 

。 Flask-Login: 管理 已 登录 用 户 的 用 户 会 话 

。 Werkzeug: 计算 密码 散 列 值 并 进行 核对 

。 itsdangerous: 生成 并 核对 加 密 安全 令 牌 

除了 身份 验证 相关 的 包 之 外 ， 本 章 还 将 用 到 如 下 常规 用 途 的 扩展 。 

。 Flask-Mail: 发 送 与 身份 验证 相关 的 电子 邮件 

。 Flask-Bootstrap: HTML 模板 

。 Flask-WTF: Web 表单 


8.2 ”密码 安全 性 


设计 Web 应 用 时 ， 人 们 往往 会 忽视 数据 库 中 用 户 信息 的 安全 性 。 如 果 攻 击 者 入 侵 服务 器 ， 
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抽取 了 数据 库 ， 用 户 的 安全 就 处 在 风险 之 中 ， 而 且 这 个 风险 超 平 你 的 想象 。 众 所 周知 ， 多 
数 用 户 会 在 不 同 的 网 站 中 使 用 相同 的 密码 。 因 此 ， 即 便 不 保存 任何 敏感 信息 ， 攻 击 者 获得 
存储 在 数据 库 中 的 密码 之 后 ， 也 能 访问 用 户 在 其 他 网 站 中 的 账户 。 


若 想 保证 数据 库 中 用 户 密码 的 安全 ， 关 键 在 于 不 存储 密码 本 身 ， 而 是 存储 密码 的 散 列 值 。 
计算 密码 散 列 值 的 函数 接收 密码 作为 输入 ， 添 加 随机 内 容 〈 盐 值 ) 之 后 ， 使 用 多 种 单 向 加 
密 算法 转换 密码 ， 最 终 得 到 一 个 和 原始 密码 没有 关系 的 字符 序列 ， 而 且 无 法 还 原 成 原始 密 
码 。 核 对 密码 时 ， 密 码 散 列 值 可 代替 原始 密码 ， 因 为 计算 散 列 值 的 函数 是 可 复 现 的 : 只 

输入 (密码 和 盐 值 ) 一 样 ， 结 果 就 一 样 。 


计算 密码 散 列 值 是 个 复杂 的 任务 ， 很 难 正确 处 理 。 因 此 强烈 建议 你 不 要 自己 
实现 ， 而 是 使 用 经 过 社区 成 员 审查 且 声 誉 良好 的 库 。 下 一 节 将 演示 Werkzeug 
的 密码 散 列 函数 的 用 法 。 此 外 ， 还 可 以 使 用 bcrypt 和 Passlib 计算 密码 的 散 
列 值 。 如 果 你 对 生成 安全 密码 散 列 值 的 过 程 感 兴趣 ，Defuse Security 的 文章 
“Salted Password Hashing - Doing it Right” 值 得 一 读 。 



























































使 用 Werkzeug 计 算 密码 散 列 值 

Werkzeug 中 的 security 模块 实现 了 密码 散 列 值 的 计算 。 这 一 功能 的 实现 只 需要 两 个 国 数 ， 

分 别 用 在 注册 和 核对 两 个 阶段 。 

generate_password_hash(password, method='pbkdf2:sha256', salt_length=8) 
这 个 函数 的 输入 为 原始 密码 ， 返 回 密码 散 列 值 的 字符 串 形式 ， 供 存 入 用 户 数 据 库 。 
method 和 salt_length 的 默认 值 就 能 满足 大 多 数 需 求 。 

check_password_hash(hash, password) 
这 个 函数 的 参数 是 从 数据 库 中 取 回 的 密码 散 列 值 和 用 户 输入 的 密码 。 返 回 值 为 True 时 
表明 用 户 输 入 的 密码 正确 。 

在 第 5 章 创建 的 User 模型 的 基础 上 添加 密码 散 列 所 需 的 改动 ， 如 示例 8-1 所 示 。 

示例 8-1 app/models.py: 在 User 模型 中 加 入 密码 散 列 


from werkzeug.security import generate password_hash, check_password_hash 

















class User(db.Model): 
# 
password_hash = db.Column(db.String(128)) 


@property 
def password(self): 
raise AttributeError('password is not a readable attribute') 


@password. setter 
def password(self, password): 
self.password_hash = generate_password_hash(password) 





def verify_password(self, password): 
return check_password_hash(self.password_hash, password) 


计算 密码 散 列 值 的 函数 通过 名 为 password 的 只 写 属 性 实现 。 设 定 这 个 属性 的 值 时 ， 赋 
值 方法 会 调用 Werkzeug 提供 的 generate_password_hash() 函数 ， 并 把 得 到 的 结果 写 入 
password_hash 字段 。 如 果 试 图 读 取 password 属性 的 值 ， 则 会 返回 错误 ,原因 很 明显 ， 
为 生成 散 列 值 后 就 无 法 还 原 成 原来 的 密码 了 。 

verify_password() 方法 接受 一 个 参数 ( 即 密码 )， 将 其 传 给 Werkzeug 提供 的 check_ 
password_hash() 国 数 ， 与 存储 在 User 模型 中 的 密码 散 列 值 进行 比 对 。 如 果 这 个 方法 返回 
True， 表 明 密 码 是 正确 的 。 
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如 果 你 从 GitHub 上 克隆 了 这 个 应 用 的 Git 仓库 ， 那 么 可 以 执行 git checkout 
8a 检 出 应 用 的 这 个 版 本 。 














密码 散 列 功能 已 经 完成 ， 下 面 在 shell 中 测试 一 下 : 


(venv) $ flask shell 
>>> U = User() 
>>> U.password = 'cat' 
>>> U.password 
Traceback (most recent call last): 
File "<console>", line 1, in <module> 
File "/home/flask/flasky/app/models.py", line 24, in password 
raise AttributeError('password is not a readable attribute') 
AttributeError: password is not a readable attribute 
>>> U.password_hash 
'pbkdf2:sha256:50000$moHwFH1B$ef1574909f9c549285e8547cad181c5e0213cfa44a4aba4349 
fa830aalfd227f'" 
>>> uy.verify_password('cat') 
True 
>>> Uy.verify_password('dog') 
False 
>>> U2 = User() 
>>> U2.password = 'cat' 
>>> U2.password_hash 
'pbkdf2:sha256:50000$PfzOmOKU$27be930b7fOe0119d38e8d8a62f7f5e75c0a7db61ae16709bc 
aa6cfd60c44b74' 


注意 ， 尝 试 访问 password 属性 会 返回 AttributeError。 另 外 ， 即 使 用 户 u 和 u2 使 用 了 相 
同 的 密码 ， 它 们 的 密码 散 列 值 也 完全 不 一 样 。 为 了 确保 这 个 功能 今后 依然 能 使 用 ， 我 们 可 
以 把 上 述 手 动 测试 的 过 程 写成 单元 测试 ， 以 便 重 复 执行 。 在 tests 包 中 新 建 一 个 模块 ， 编 写 
3 个 新 测试 ， 测 试 最 近 对 User 模型 所 做 的 改动 ， 如 示例 8-2 所 示 。 


示例 8-2 ”tests/test_user_model.py: 密码 散 列 测试 


import unittest 
from app.models import User 











也 


class UserModelTestCase(unittest.TestCase): 
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def test_password_setter(seLf) : 
U = User(password = 'cat') 


seLf .assertTrue(u.password_hash is not None) 


def test_no_password_getter(seLf) : 
uU = User(password = "cat ') 


with self.assertRaises(AttributeError): 


U.password 


def test_ password_ verification(self): 
uU = User(password = 'cat') 


seLf .assertTrue(u.verify_password('cat')) 
seLf .assertFaLse(u.Vverify_password('dog' )) 


def test_password_saLts_are_random(seLf) : 
U = User(password='cat') 
U2 = User(password='cat') 


seLf .assertTrue(u.password_hash != uy2.password_hash) 


执行 下 述 命令 ， 运 行 新 增 的 单元 测试 : 


(venv) $ fLask test 





test_app_exists (test basics.BasicsTestCase) ... ok 

test_app_is testing (test basics.BasicsTestCase) ... 
test_no_password_getter (test user_ model.UserModelTestCase) ... ok 
test_password_salts_are_random (test user_model.UserModelTestCase) ... ok 
test_password_setter (test user_model.UserModelTestCase) ... ok 
test_password_verification (test user_model.UserModelTestCase) ... ok 


Ran 6 tests in 0.379s 


OK 


每 次 想 确 认 一 切 功能 是 否 正常 时 ， 就 可 以 运行 单元 测试 组 件 。 通 过 








自动 化 测试 验证 功能 不 





费 吹 灰 之 力 ， 因 此 应 该 经 常 运 行 ， 确 保 以 后 的 改动 不 会 破坏 现在 可 用 的 功能 。 











8.3 创建 身份 验证 蓝 

















我 们 在 第 7 章 介绍 过 蓝本 ， 把 创建 应 用 的 过 程 移入 工厂 函数 后 ， 可 使 用 蓝本 在 全 局 作用 域 
中 定义 路 由 。 本 节 将 在 一 个 新 蓝本 中 定义 与 用 户 身份 验证 子 系统 相关 的 路 由 ， 这 个 蓝本 名 
为 auth。 把 应 用 的 不 同 子 系统 放 在 不 同 的 蓝本 中 ， 有 利于 保持 代码 整洁 有 序 。 


auth 蓝本 保存 在 同名 Python 包 中 。 这 个 蓝本 的 包 构 造 函 数 创建 蓝本 对 象 ， 再 从 views.py 








模块 中 导入 路 由 ， 代 码 如 示例 8-3 所 示 。 


示例 8-3 ”app/auth/_init .py: 创建 身份 验证 监 本 
from flask import Blueprint 


auth = Blueprint('auth', __name_) 


from . import views 





app/auth/views.py 模块 导入 蓝本 ， 然 后 使 用 蓝本 的 route 装饰 器 定义 与 身份 验证 相关 的 路 
由 ， 如 示例 8-4 所 示 。 这 段 代码 添加 了 一 个 /login 路 由 ， 演 染 同 名 占 位 模板 。 


示例 8-4 app/auth/views.py: 身份 验证 蓝本 中 的 路 由 和 视图 函数 
from flask import render_template 
from . import auth 


@auth.route('/login') 
def login(): 
return render_template('auth/login.html') 
注意 ， 为 render_template() 指定 的 模板 文件 保存 在 auth 目录 中 。 这 个 目录 必须 在 app/ 
templates 中 创建 ， 因 为 Flask 期 望 模板 的 路 径 是 相对 于 应 用 的 模板 目录 而 言 的 。 把 蓝本 中 
用 到 的 模板 放 在 单独 的 子 目 录 中 ， 能 避免 与 main 蓝本 或 以 后 添加 的 蓝本 发 生 冲 突 。 


我 们 也 可 以 配置 蓝本 使 用 专门 的 目录 保存 模板 。 如 果 配 置 了 多 个 模板 目录 ， 
那么 render_template() 函数 会 先 搜索 应 用 的 模板 目录 ， 然 后 再 搜索 蓝本 的 
模板 目录 。 






































auth 蓝本 要 在 create_app() 工厂 函数 中 附加 到 应 用 上 ， 如 示例 8-5 所 示 。 
示例 8-5 app/_init .py: 注册 身份 验证 蓝本 


def create_app(config_name) : 
# a 
from .auth import auth as auth_bLueprint 
app.register_blueprint(auth_blueprint, url_prefix='/auth') 


return app 


注册 蓝本 时 使 用 的 url_prefix 是 可 选 参 数 。 如 果 使 用 了 这 个 参数 ， 注 册 后 蓝本 中 定义 的 
所 有 路 由 都 会 加 上 指定 的 前 级 ， 即 这 个 例子 中 的 /auth。 例 如 ，/login 路 由 会 注册 成 /auth/ 
login， 在 开发 Web 服务 器 中 ， 完 整 的 URL 就 变 成 了 http://localhost:5000/auth/login。 





如 果 你 从 GitHub 上 克隆 了 这 个 应 用 的 Git 仓库 ， 那 么 可 以 执行 git checkout 
8b 检 出 应 用 的 这 个 版 本 。 














8.4 使 用 Flask-Login 验 证 用 户 身份 


用 户 登 录 应 用 后 ， 他 们 的 验证 状态 要 记录 在 用 户 会 话 中 ,这样 浏览 不 同 的 页 面 时 才能 记 住 
这 个 状态 。Flask-Login 是 个 非常 有 用 的 小 型 扩展 ， 专 门 用 于 管理 用 户 身 份 验证 系统 中 的 验 
证 状态 ， 且 不 依赖 特定 的 身份 验证 机 制 。 


使 用 之 前 ， 要 在 虚拟 环境 中 安装 这 个 扩展 : 


(venv) $ pip install flask-login 
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8.4.1 准备 用 于 登录 的 用 户 模 型 


Flask-Login 的 运转 需要 应 用 中 有 User 对 象 。 要 想 使 用 Flask-Login 扩展 ， 应 用 的 User 模型 
必须 实现 几 个 属性 和 方法 ， 如 表 8-1 所 示 。 


表 8-1: Flask-Login 要 求实 现 的 属性 和 方法 

























































































属性 /方法 说 明 

is_authenticated 如 果 用 户 提 供 的 登录 凭据 有 效 ， 必 须 返 回 True， 否 则 返回 False 

is_active 如 果 人 允许 用 户 登 录 ， 必 须 返 回 True， 否 则 返回 False。 如 果 想 禁用 账户 ， 可 以 返回 False 
is_anonymous 对 普通 用 户 必 须 始终 返回 False， 如 果 是 表示 匿名 用 户 的 特殊 用 户 对 象 ， 应 该 返回 True 
get_id() 必须 返回 用 户 的 唯一 标识 符 ， 使 用 Unicode 编码 字符 串 














这 些 属性 和 方法 可 以 直接 在 模型 类 中 实现 ， 不 过 还 有 一 种 更 简单 的 替代 方案 。Flask-Login 
提供 了 一 个 UserMixin 类 ， 其 中 包含 默认 实现 ， 能 满足 多 数 需求 。 修 改 后 的 User 模型 如 示 
例 8-6 所 示 。 


示例 8-6 app/models.py: 修改 User 模型 ， 支 持 用 户 登录 


from flask_login import UserMixin 





class User(UserMixin, db.Model): 
_tablename _ = "Users' 
id = db.Column(db.Integer, primary_key = True) 
email = db.Column(db.String(64), unique=True, index=True) 
username = db.Column(db.String(64), unique=True, index=True) 
password_hash = db.Column(db.String(128)) 
role_id = db.Column(db.Integer, db.ForeignKey('roles.id')) 


注意 ， 这 个 示例 中 还 添加 了 email 字段 。 在 这 个 应 用 中 ， 用 户 使 用 电子 邮件 地 址 登录 ， 
为 相对 于 用 户 名 而 言 ， 用 户 更 不 容易 忘记 自己 的 电子 邮件 地 址 。 


Flask-Login 在 应 用 的 工厂 函数 中 初始 化 ， 如 示例 8-7 所 示 。 
示例 8-7 app/_init _.py: 初始 化 Flask-Login 


from flask_login import LoginManager 





tH 

















login manager = LoginManager() 
login manager .login view = "auth.Login' 


def create_app(config name): 


login_ manager.init_app(app) 
i 


LoginManager 对 象 的 Login_view 属性 用 于 设置 登录 页 面 的 端点 。 匿 名 用 户 尝试 访问 受 保护 
的 页 面 时 ，Flask-Login 将 重 定 向 到 登录 页 面 。 因 为 登录 路 由 在 蓝本 中 定义 ， 所 以 要 在 前 面 
加 上 蓝本 的 名 称 。 


最 后 ，Flask-Login 要 求 应 用 指定 一 个 函数 ， 在 扩展 需要 从 数据 库 中 获取 指定 标识 符 对 应 自 
用 户 时 调用 。 这 个 函数 的 定义 如 示例 8-8 所 示 。 
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示例 8-8 app/models.py: 加 载 用 户 的 函数 
from . import Login_manager 
@login_manager .user_loader 


def load user(user_id): 
return User.query.get(int(user_id)) 


login_manager .user_loader 装饰 器 把 这 个 函数 注册 给 Flask-Login， 在 这 个 扩展 需要 获取 已 
登录 用 户 的 信息 时 调用 。 传 入 的 用 户 标识 符 是 个 字符 串 ， 因 此 这 个 函数 先 把 标识 符 转 换 成 
整数 ， 然 后 传 给 Flask-SQLAlchemy 查询 ， 加 载 用 户 。 正 常情 况 下 ， 这 个 函数 的 返回 值 必 
须 是 用 户 对 象 ， 如 果 用 户 标 识 符 无 效 ， 或 者 出 现 了 其 他 错误 ， 则 返回 None。 


8.4.2 ”保护 路 由 


为 了 保护 路 由 ， 只 让 通过 身份 验证 的 用 户 访问 ，Flask-Login 提供 了 一 个 Login_required 装 
饰 器 。 其 用 法 演示 如 下 : 


from flask_login import login_required 



































@app.route('/secret') 
@login_required 
def secret(): 
return 'Only authenticated users are allowed!' 


从 这 个 示例 可 以 看 出 ， 多 个 函数 装饰 器 可 以 琶 加 使 用 。 函 数 上 有 多 个 装饰 器 时 ， 各 装饰 器 
只 对 随后 的 装饰 器 和 目标 函数 起 作用 。 在 这 个 示例 中 ，secret() 函数 受 login_required 装 
饰 器 的 保护 ， 禁 止 未 授权 的 用 户 访问 ， 得 到 的 函数 又 注册 为 一 个 Flask 路 由 。 如 果 调 换 两 
个 装饰 器 ， 得 到 的 结果 将 是 错 的 ， 因 为 原始 函数 先 注册 为 路 由 ， 然 后 才 从 login_required 
装饰 器 接收 到 额外 的 属性 。 


得 益 于 Login_required 装饰 器 ， 如 果 未 通过 身份 验证 的 用 户 访问 这 个 路 由 ，Flask-Login 将 
拦截 请 求 ， 把 用 户 发 往 登 录 页 面 。 


8.4.3 添加 登录 表单 


呈现 给 用 户 的 登录 表单 中 包含 一 个 用 于 输入 电子 邮件 地 址 的 文本 字段 、 一 个 密码 字段 、 一 
个 “ 记 住 我 ” 复 选 框 和 一 个 提交 按钮 。 这 个 表单 使 用 的 Flask-WTF 类 如 示例 8-9 所 示 。 


示例 8-9 app/auth/forms.py: 登录 表单 
from fLask_wtf import FLaskForm 
from wtforms import StringField, PasswordField, BooleanField, SubmitField 
from wtforms.validators import DataRequired, Length, Email 
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class LoginForm(FlaskForm): 
email = StringField('Email', validators=[DataRequired(), Length(1, 64), 
Email()]) 
password = PasswordField('Password', validators=[DataRequired()]) 
remember_me = BooleanField('Keep me logged in') 
submit = SubmitField('Log In') 
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PasswordField 类 表示 属性 为 type="password" 的 <input> 元 素 。BooleanField 类 表示 复 选 框 。 

电子 邮件 字段 用 到 了 WTForms 提供 的 Length()、Email() 和 DataRequired() 这 3 个 验证 函 
数 ， 不 仅 确 保 这 个 字段 有 值 ， 而 且 必 须 是 有 效 的 。 提 供 验 证 函数 列表 时 ，WTForms 将 按照 
指定 的 顺序 执行 各 个 验证 函数 。 倘 车 验 证 失败 ， 显 示 的 错误 消息 将 是 首 个 失败 的 验证 函数 


的 消息 oo 








登录 页 面 使 用 的 模板 保存 在 auth/login.html 文件 中 。 这 个 模板 只 需 使 用 Flask-Bootstrap 
quick_form() 宏 泻 染 表 单 即 可 。 登 录 表单 在 浏览 器 中 泻 染 后 的 样子 如 图 8-1 








提供 的 wtf. 


所 示 。 
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8-1: 登录 表单 





base.html 模板 中 的 导航 栏 可 以 使 用 Jinja2 条 件 语 名 判断 当前 用 户 的 登录 状态 ， 分 别 显示 
Log In 或 Log Out 链接 。 这 个 条 件 语 句 如 示例 8-10 所 示 。 


示例 8-10 


app/templates/base.html: 导航 栏 中 的 Log In 和 Log Out 链接 


<ul class="nav navbar-nav navbar-right"> 


{% 


if current_user.is_authenticated %} 


<li><a href="{{ url_for('auth.logout') }}">Log Out</a></li> 


{% 


else %} 


<li><a href="{{ url_for('auth.login’') }}">Log In</a></li> 


{% 
</ul> 


endif %} 


判断 条 件 中 的 变量 current_user 由 Flask-Login 定义 ， 在 视图 函数 和 模板 中 自动 可 用 。 这 
个 变量 的 值 是 当前 登录 的 用 户 ， 如 果 用 户 未 登录 ， 则 是 一 个 匿名 用 户 代理 














对 象 。 


匿名 用 户 











入 后 
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对 象 的 is_authenticated 属性 值 是 False， 所 以 通过 current_user.is_authenticated 表达 
式 就 能 判断 当前 用 户 是 否 登 录 。 


8.4.4 登入 用 户 
视图 函数 Login() 的 实现 如 示例 8-11 所 示 。 


示例 8-11 app/auth/views.py: 登录 路 由 


from flask import render_template, redirect, request, url_for, flash 
from flask_login import login user 

from . import auth 

from ..models import User 

from .forms import LoginForm 








@auth.route('/login', methods=['GET', 'POST']) 
def login(): 
form = LoginForm() 
if form.validate on_submit(): 
User = User.query.filter_by(email=form.email.data).first() 
if user is not None and user.verify_ password(form.password.data): 
login user(user, form.remember_me.data) 
next = request.args.get('next') 
if next is None or not next.startswith('/'): 
next = url_for('main.index') 
return redirect(next) 
flash('Invalid username or password.') 
return render_template('auth/login.html', form=form) 


这 个 视图 函数 创建 了 一 个 LoginForm 对 象 ， 用 法 和 第 4 章 中 的 那个 简单 表单 一 样 。 当 请 
求 类 型 是 GET 时 ， 视 图 函数 直接 渲染 模板 ， 即 显示 表单 。 当 表单 通过 POST 请 求 提交 时 ， 
Flask-WTF 的 validate_on_submit() 函数 会 验证 表单 数据 ， 然 后 尝试 登入 用 户 。 


为 了 登入 用 户 ， 视 图 函数 首先 使 用 表单 中 填写 的 电子 邮件 地 址 从 数据 库 中 加 载 用 户 。 如 果 
电子 邮件 地 址 对 应 的 用 户 存在 ， 再 调用 用 户 对 象 的 verify_password() 方法 ， 其 参数 是 表 
单 中 填写 的 密码 。 如 果 密 码 正 确 ， 调 用 Flask-Login 的 Login_user() 函数 ， 在 用 户 会 话 中 
把 用 户 标 记 为 已 登录 。Login_user() 函数 的 参数 是 要 登录 的 用 户 ， 以 及 可 选 的 “ 记 住 我 ” 
布尔 值 ,“ 记 住 我 ”也 在 表单 中 色 选 。 如 果 这 个 字段 的 值 为 False， 关 闭 浏览 器 后 用 户 会 话 
就 过 期 了 ， 所 以 下 次 用 户 访问 时 要 重新 登录 。 如 果 值 为 True， 那么 会 在 用 户 浏览 器 中 写 和 人 
一 个 长 期 有 效 的 cookie， 使 用 这 个 cookie 可 以 复 现 用 户 会 话 。cookie 默认 记 住 一 年 ， 可 以 
使 用 可 选 的 REMEMBER_COOKIE_DURATION 配置 选项 更 改 这 个 值 。 


按照 第 4 章 介绍 的 “Post / 重 定向 /Get 模式 ”， 提 交 登 录 凭据 的 POST 请 求 最 后 也 做 了 重 
向 ， 不 过 目标 URL 有 两 种 可 能 。 用 户 访问 未 授权 的 URL 时 会 显示 登录 表单 ，Flask-Login 
会 把 原 URL 保存 在 查询 字符 串 的 next 参数 中 ， 这 个 参数 可 从 request .args 字典 中 读 取 。 
如 果 查 询 字符 串 中 没有 next 参数 ， 则 重 定向 到 首页 。next 参数 中 的 URL 会 经 验证 ， 确 保 
是 相对 URL， 以 防 恶意 用 户 利 用 这 个 参数 ， 把 不 知情 的 用 户 重 定向 到 其 他 网 站 。 


如 果 用 户 输入 的 电子 邮件 地 址 或 密码 不 正确 ， 应 用 会 设 定 一 个 闪现 消息 ， 并 再 次 泻 染 表 
单 ， 让 用 户 再 次 尝试 登录 。 
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在 生产 服务 器 上 ， 应 用 必须 使 用 安全 的 HITP， 保 证 始终 以 加 密 的 方式 传输 
登录 凭据 和 用 户 会 话 。 如 果 没 使 用 安全 的 HTTP， 敏 感 数 据 在 传输 过 程 中 可 
能 会 被 攻击 者 截获 。 





我 们 需要 更 新 登录 模板 ， 泻 染 这 个 表单 。 修 改 后 的 模板 如 示例 8-12 所 示 。 


示例 8-12 ”app/templates/auth/login.html: 登录 表单 模板 


{% extends "base.html" %} 
{% import "bootstrap/wtf.html" as wtf %} 


{% block title %}Flasky - Login{% endblock %} 


{% block page_content %} 

<div class="page-header"> 
<h1>Login</h1> 

</div> 

<div class="col-md-4"> 
{{ wtf.quick_form(form) }} 

</div> 

{% endblock %} 


8.4.5 登 出 用 户 
退出 路 由 的 实现 如 示例 8-13 所 示 。 
示例 8-13 app/auth/views.py: 退出 路 由 


from flask_login import Logout_User，Login_required 


Qauth.route(' /Logout ' ) 

@login_required 

def logout(): 
Logout_user() 
flash('You have been logged out.') 
return redirect(url_for('main.index')) 


为 了 登 出 用 户 ， 这 个 视图 函数 调用 Flask-Login 的 Logout_user() 函数 ， 删 除 并 重 设 用 户 会 
话 。 随 后 会 显示 一 个 闪现 消 息 ， 确 认 这 次 操作 ， 然 后 重 定 向 到 首页 ， 这 样 就 成 功 退 出 了 。 








如 果 你 从 GitHub 上 克隆 了 这 个 应 用 的 Git 仓库 ， 那 么 可 以 执行 git checkout 
8c 检 出 应 用 的 这 个 版 本 。 这 次 更 新 包含 一 个 数据 库 迁 移 ， 所 以 检 出 代码 后 
记得 要 执行 flask db upgrade 命令 。 为 保证 安装 了 所 有 依赖 ， 还 要 运行 pip 


install -r requirements.txt, 








8.4.6 理解 Flask-Login 的 运作 方式 


Flask-Login 是 个 相当 小 的 扩展 ， 但 是 身份 验证 流程 中 有 太 多 变动 部 分 ， 因 此 Flask 用 户 往 
往 难 以 理解 这 个 扩展 的 运作 方式 。 用 户 登录 过 程 涉及 以 下 操作 步骤 。 
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(1) 用 户 点 击 Log In 链接 ， 访 问 http://localhost:5000/auth/login。 处 理 这 个 URL 的 函数 返回 
登录 表单 模板 。 
(2) 用 户 输入 用 户 名 和 密码 ， 然 后 点 击 提交 按钮 。 再 次 调用 相同 的 处 理 函 数 ， 不 过 这 一 次 处 
理 的 是 PosT 请 求 ， 而 非 GET 请 求 。 
a， 处理 函 数 验 证 通过 表单 提交 的 凭据 ， 然 后 调用 Flask-Login 的 tlogin_user() 函数 ， 登 
入 用 户 。 
b. login_user() 函数 把 用 户 的 ID 以 字符 串 的 形式 写 入 用 户 会 话 。 
c， 视 图 函数 重 定向 到 首页 。 
(3) 浏览 器 收 到 重 定向 响应 ， 请 求 首 页 。 
a， 调用 首页 的 视图 函数 ， 演 染 主 页 的 Jinja2 模板 。 
b. 在 泻 染 这 个 Jinja2 模板 的 过 程 中 ， 首 次 出 现 对 Flask-Login 的 current_user 的 引用 。 
c. 这 个 请 求 还 没有 给 上 下 文 变量 current_user 赋值 ， 因 此 调用 Flask-Login 内 部 的 
_get_user() 函数 ， 找 出 用 户 是 谁 。 
d.，_get_user() 函数 检查 用 户 会 话 中 有 没有 用 户 ID。 如 果 没 有 ， 返 回 一 个 Flask-Login 
的 AnonymousUser 实例 。 如 果 有 ID， 调 用 应 用 中 使 用 user_loader 装饰 器 注册 的 函 
数 ， 传 和 用 户 ID。 
.应 用 中 的 user_loader 处 理 函 数 从 数据 库 中 读 取 用 户 ， 将 其 返回 。Flask-Login 把 返 
回 的 用 户 对 象 赋值 给 当前 请 求 的 current_user 上 下 文 变量 。 
f， 模 板 收 到 新 赋值 的 current_user。 


使 用 Login_required 装饰 器 装饰 的 视图 函数 将 使 用 current_user 上 下 文 变量 判断 current_ 
user .is_authenticated 表达 式 的 结果 是 否 为 True。logout_user() 函数 就 简单 了 ， 它 直接 
从 用 户 会 话 中 把 用 户 ID 删除 。 


8.4.7 ”登录 测试 


为 验证 登录 功能 可 用 ， 可 以 更 新 首页 ， 使 用 已 登录 用 户 的 名 字 显 示 一 个 欢迎 消息 。 模 板 中 
生成 欢迎 消息 的 部 分 如 示例 8-14 所 示 。 


示例 8-14 app/templates/index.html: 为 已 登录 的 用 户 显 示 一 个 欢迎 消息 
Hello, 
{% if current user.is authenticated %} 
{{ current_user .username }} 
{% else %} 
Stranger 
{% endif %}! 


这 个 模板 再 次 使 用 current_user .is_authenticated 判断 用 户 是 否 已 经 登录 。 
因为 还 未 实现 用 户 注册 功能 ， 所 以 目前 只 能 在 shell 中 注册 新 用 户 : 


(venv) $ flask shell 

>>> U = User(email='john@example.com', username="'john', password='cat') 
>>> db.session.add(u) 

>>> db.session.commit() 


刚刚 创建 的 用 户 现在 可 以 登录 了 。 用 户 登录 后 显示 的 首页 如 图 8-2 所 示 。 
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O90 氏 _| Flasky 


€ C 合 @Iiocalhost:5000 





Hello, john! 





8-2: 成 功 登录 后 的 首页 


8.5 注册 新 用 户 


如 果 新 用 户 想 成 为 应 用 的 成 员 ， 必 须 在 应 用 中 注册 ， 这 样 应 用 才能 识别 并 登 和 用户。 应 用 
的 登录 页 面 中 要 显示 一 个 链接 ， 把 用 户 带 到 注册 页 面 ， 让 用 户 输入 电子 邮件 地 址 、 用 户 名 
和 密码 。 


8.5.1 添加 用 户 注 册 表 单 
注册 页 面 中 的 表单 要 求 用 户 输入 电子 邮件 地 址 、 用 户 名 和 密码 。 这 个 表单 如 示例 8-15 所 示 。 
示例 8-15 app/auth/forms.py: 用 户 注册 表单 























from flask_ wtf import FLaskForm 

from wtforms import StringField, PasswordField, BooleanField, SubmitField 
from wtforms.validators import DataRequired, Length, Email, Regexp, EqualTo 
from wtforms import ValidationError 

from ..modeLs import User 


class RegistrationForm(FlaskForm): 
email = StringField('Email', validators=[DataRequired(), Length(1, 64), 
Email()]) 
username = StringField('Username', validators=[ 
DataRequired(), Length(1, 64), 
Regexp('^[A-Za-z][A-Za-z0-9_.]*$', 0, 
"Usernames must have only letters, numbers, dots or 
'underscores' )]) 
password = PasswordField('Password', validators=[ 
DataRequired(), EqualTo('password2', message='Passwords must match.')]) 
password2 = PasswordField('Confirm password', validators=[DataRequired()]) 








submit = SubmitField('Register') 


def validate email(self, field): 
if User .query.filter_by(email=field.data).first(): 
raise ValidationError('Email already registered.') 


def validate username(self, field): 
if User.query.filter_by(username=field.data).first(): 
raise ValidationError('Username already in use.') 


这 个 表单 使 用 WTForms 提供 的 Regexp 验证 函数 ， 确 保 username 字段 的 值 以 字母 开头 ， 而 
且 只 包 仿 字母、 数字、 下 划 线 和 点 号 。 这 个 验证 函数 中 正则 表达 式 后 面 的 两 个 参数 分 别 是 
正则 表达 式 的 标志 和 验证 失败 时 显示 的 错误 消息 。 

为 了 安全 起 见 ， 密 码 要 输入 两 次 。 此 时 要 验证 两 个 密码 字段 中 的 值 是 否 一致 ， 这 种 验证 可 
使 用 WTForms 提供 的 另 一 验证 函数 实现 ， 即 EquatTo。 这 个 验证 函数 要 附属 到 两 个 密码 字 
段 中 的 一 个 上 ， 另 一 个 字段 则 作为 参数 传 入 。 

这 个 表单 还 有 两 个 自 定义 的 验证 函数 ， 以 方法 的 形式 实现 。 如 果 表 单 类 中 定义 了 以 validate_ 
开头 且 后 面 跟着 字段 名 的 方法 ， 这 个 方法 就 和 常规 的 验证 函数 一 起 调用 。 本 例 分 别 为 
email 和 username 字段 定义 了 验证 函数 ， 确 保 填 写 的 值 在 数据 库 中 没 出 现 过 。 自 定义 的 
验证 函数 要 想 表 示 验 证 失败 ， 可 以 抛 出 ValidationError 异常 ， 其 参数 就 是 错误 消息 。 
显示 这 个 表单 的 模板 是 /templates/auth/register.html。 与 登录 模板 一 样 ， 这 个 模板 也 使 用 
wtf.quick_form() 演 染 表单 。 注 册页 面 如 图 8-3 所 示 。 
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€ CO © localhost:5000/auth/register 





Register 


Email 
Username 
Password 


Confirm password 


Register 











图 8-3: 新 用 户 注册 表单 
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登录 页 面 要 显示 一 个 指向 注册 页 面 的 链接 ， 让 没有 账户 的 用 户 能 轻松 找到 注册 页 面 。 改 动 
如 示例 8-16 所 示 。 


示例 8-16 ”app/templates/auth/login.html: 链接 到 注册 页 面 
<p> 
New user? 
<a href="{{ url_for('auth.register') }}"> 
Click here to register 
</a> 
</p> 


8.5.2 注册 新 用 户 


处 理 用 户 注册 的 过 程 没有 什么 难以 理解 的 地 方 。 提 交 注 册 表 单 ， 通 过 验证 后 ， 系 统 使 用 用 
户 填写 的 信息 在 数据 库 中 添加 一 个 新 用 户 。 处 理 这 个 任务 的 视图 函数 如 示例 8-17 所 示 。 


示例 8-17 app/auth/views.py: 用 户 注册 路 由 


@auth.route('/register', methods=['GET', 'POST']) 
def register(): 

form = RegistrationForm() 

if form.validate on_submit(): 

User = User(email=form.email.data, 
username=form.username.data, 
password=form.password.data) 

db.session.add(user) 

db.session.commit() 

flash('You can now login.') 

return redirect(url_for('auth.login')) 

return render_template('auth/register.html', form=form) 



































如 果 你 从 GitHub 上 克隆 了 这 个 应 用 的 Git 仓库 ， 那 么 可 以 执行 git checkout 
8d 检 出 应 用 的 这 个 版 本 。 





* /= 
8.6 确认 账户 
对 于 某 些 特定 类 型 的 应 用 ， 有 必要 确认 注册 时 用 户 提 供 的 信息 是 否 正确 。 常 见 要 求 是 能 通 
过 提供 的 电子 邮件 地 址 与 用 户 取 得 联系 。 


为 了 确认 电子 邮件 地 址 ， 用 户 注册 后 ， 应 用 会 立即 发 送 一 封 确认 邮件 。 新 账户 先 被 标记 成 
待 确认 状态 ， 用 户 按照 邮件 中 的 说 明 操作 后 ， 才 能 证 明 自 己 可 以 收 到 电子 邮件 。 账 户 确认 
过 程 中 ， 往 往 会 要 求 用户 点 击 一 个 包含 确认 令 牌 的 特殊 URL 链接 。 


8.6.1 使 用 itsdangerous 生 成 确认 令 牌 


确认 邮件 中 最 简单 的 确认 链接 是 http://www.example.com/auth/confirm/<id> 这 种 形式 的 
URL， 其 中 <id> 是 数据 库 分 配给 用 户 的 数字 id。 用 户 点 击 链 接 后 ， 处 理 这 个 路 由 的 视图 
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函数 将 确认 收 到 的 用 户 id， 然 后 将 用 户 状态 更 新 为 已 确认 。 

但 这 种 实现 方式 显然 不 是 很 安全 ， 只 要 用 户 能 判断 确认 链接 的 格式 ， 就 可 以 随便 指定 URL 
中 的 数字 ， 从 而 确认 任意 账户 。 解 决 方法 是 把 URL 中 的 <id> 换 成 包含 相同 信息 的 令 牌 ， 
但 是 只 有 服务 器 才能 生成 有 效 的 确认 URL。 

回忆 一 下 我 们 在 第 4 章 对 用 户 会 话 的 讨论 ，Flask 使 用 加 密 的 签名 cookie 保护 用 户 会 话 ， 
以 防止 被 算 改 。 用 户 会 话 cookie 中 有 一 个 由 itsdangerous 包 生 成 的 加 密 签名 。 如 果 用 户 会 
话 的 内 容 被 算 改 ， 签 名 将 不 再 与 内 容 匹配 ， 这 样 会 使 Flask 销毁 会 话 ， 然 后 重建 一 个 。 同 
样 的 方法 也 可 用 在 确认 令 牌 上 。 


下 面 这 个 简短 的 shell 会 话 展 示 如 何 使 用 itsdangerous 包 生 成 包含 用 户 id 的 签名 令 牌 : 


(venv) $ flask sheLL 

>>> from itsdangerous import TimedJSONWebSignatureSerializer as Serializer 

>>> s = Serializer(app.config['SECRET_KEY'], expires_in=3600) 

>>> token = s.dumps({ 'confirm': 23 }) 

>>> token 

‘eyJhbGciOijJIUzI1NiIsImV4AcCI6MTMAMTCXODU1OCwiaWFOIjoxMzgxNzEQOTU4fQ.ey ...， 

>>> data = s.loads(token) 

>>> data 

{'confirm': 23} 
itsdangerous 提供 了 多 种 生成 令 牌 的 方法 。 其 中 ，TimedJSONWebSignatureSerializer 类 生 
成 具有 过 期 时 间 的 JSON Web 签名 (JWS)。 这 个 类 的 构造 函数 接收 的 参数 是 一 个 密 钥 ， 
在 Flask 应 用 中 可 使 用 SECRET_KEY 设置 。 
dumps() 方法 为 指定 的 数据 生成 一 个 加 密 签 名 ， 然 后 再 对 数据 和 签名 进行 序列 化 ， 生 成 令 
牌 字 符 串 。expires_in 参数 设置 令 牌 的 过 期 时 间 ， 单 位 为 秒 。 
为 了 解码 令 牌 ， 序 列 化 对 象 提供 了 Loads() 方法 ， 其 唯一 的 参数 是 令 牌 字符 串 。 这 个 方法 
会 检验 签名 和 过 期 时 间 ， 如 果 都 有 效 ， 则 返回 原始 数据 。 如 果 提 供给 Loads() 方法 的 令 牌 
无 效 或 是 过 期 了 ， 则 抛 出 异常 。 
我 们 可 以 把 这 种 生成 和 检验 令 牌 的 功能 添加 到 User 模型 中 ， 改 动 如 示例 8-18 所 示 。 
示例 8-18 ”app/models.py: 确认 用 户 账户 


from itsdangerous import TimedJSONWebSignatureSerializer as Serializer 
from flask import current_app 
from . import db 




















Ep 

























































































class User(UserMixin, db.Model): 
Hs 
confirmed = db.Column(db.Boolean, default=False) 


def generate confirmation_token(self, expiration=3600): 
s = Serializer(current_app.config['SECRET_KEY'], expiration) 
return s.dumps({'confirm': self.id}).decode('utf-8') 


def confirm(self, token): 
s = Serializer(current_app.config['SECRET_KEY']) 
try: 
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data = s.Loads(token.encode('utf-8')) 
except: 

return False 
if data.get('confirm') != self.id: 

return False 
self.confirmed = True 
db.session.add(self) 
return True 


generate_confirmation_token() 方法 生成 一 个 令 牌 ， 有 效 期 默认 为 一 小 时 。confirm( ) 方 
法 检验 令 牌 ， 如 果 检 验 通 过 ， 就 把 用 户 模 型 中 新 添加 的 confirmed 属性 设 为 True。 

除了 检验 令 牌 ，confirm() 方法 还 检查 令 牌 中 的 id 是 否 与 存储 在 current_user 中 的 已 登录 
用 户 匹 配 。 这 样 能 确保 为 一 个 用 户 生 成 的 确认 令 牌 无 法 用 于 确认 其 他 用 户 。 











由 于 模型 中 新 加 入 了 一 列 用 来 保存 账户 的 确认 状态 ， 因 此 要 生成 并 运行 一 个 
新 数据 库 迁 移 。 





User 模型 中 新 添加 的 两 个 方法 很 容易 进行 单元 测试 。 相 应 的 单元 测试 可 在 本 应 用 的 GitHub 
仓库 中 查看 。 
8.6.2 ”发送 确认 邮件 


当前 的 /register 路 由 把 新 用 户 添加 到 数据 库 中 之 后 ， 会 重 定向 到 /index。 在 重 定向 之 前 ， 
这 个 路 由 现在 需要 发 送 确认 邮件 。 改 动 如 示例 8-19 所 示 。 


示例 8-19 app/auth/views.py: 能 发 送 确认 邮件 的 注册 路 由 


from ..email import send_email 














@auth.route('/register', methods=['GET', 'POST']) 
def register(): 
form = RegistrationForm() 
if form.validate on_submit(): 
a 
db.session.add(user) 
db.session.commit() 
token = user.generate confirmation_token() 
send_email(user.email, 'Confirm Your Account ' ， 
'auth/email/confirm', user=user, token=token) 
flash('A confirmation email has been sent to you by email.') 
return redirect(url_for('main.index')) 
return render_template('auth/register.html', form=form) 














注意 ， 在 发 送 确认 邮件 之 前 要 调用 db.session.commit()。 之 所 以 这 么 做 ,是 因为 提交 之 后 
才能 赋予 新 用 户 id 值 ， 而 确认 令 牌 需要 用 到 id。 


身份 验证 蓝本 使 用 的 电子 邮件 模板 保存 在 templates/auth/email 目录 中 ， 以 便 与 HTML 模板 区 
分 开 来 。 第 6 章 说 过 ,一 个 电子 邮件 需要 两 个 模板 ,分 别 用 于 渲染 纯 文本 正文 和 HTML 正 
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文 。 举 个 例子 ， 示 例 8-20 是 确认 邮件 模板 的 纯 文 本 版 本 ， 对 应 的 HIML 版 本 可 到 GitHub 仓 
库 中 查看 。 


示例 8-20 ”app/templates/auth/email/confirm.txt: 确认 邮件 的 纯 文本 正文 


Dear {{ user.username }}, 





Welcome to Flasky! 

To confirm your account please click on the following link: 
{{ url_for('auth.confirm', token=token, _external=True) }} 
Sincerely, 

The Flasky Team 

Note: replies to this email address are not monitored. 


默认 情况 下 ，urtL_for() 生成 相对 URL， 例 如 urL_for('auth.confirm' ，token='abc') 返 
回 的 字符 串 是 '/auth/confirm/abc'。 这 显然 不 是 能 够 在 电子 邮件 中 发 送 的 正确 URL， 因 
为 只 有 URL 的 路 径 部 分 。 相 对 URL 在 网 页 的 上 下 文中 可 以 正常 使 用 ， 因 为 浏览 器 会 添加 
当前 页 面 的 主机 名 和 端口 号 ， 将 其 转换 成 绝对 URL。 但 是 通过 电子 邮件 发 送 的 URL 并 没 
有 这 种 上 下 文 。 添 加 到 url_for() 函数 中 的 _external=True 参数 要 求 应 用 生成 完全 限定 的 
URL， 包 括 协议 (http:// 或 https:/)、 主 机 名 和 端口 。 


确认 账户 的 视图 函数 如 示例 8-21 所 示 。 
示例 8-21 app/auth/views.py: 确认 用 户 的 账户 


from flask_login import current_user 


























@auth.route('/confirm/<token>') 
@login_required 
def confirm(token): 
if current_user.confirmed: 
return redirect(url_for('main.index')) 
if current user.confirm(token): 
db.session.commit() 
flash('You have confirmed your account. Thanks!') 
else: 
flash('The confirmation link is invalid or has expired.') 
return redirect(url_for('main.index')) 


Flask-Login 提供 的 Login_required 装饰 器 会 保护 这 个 路 由 ， 因 此 ， 用 户 点 击 确认 邮件 中 的 
链接 后 ， 要 先 登 录 ， 然 后 才能 执行 这 个 视图 函数 。 

这 个 函数 先 检查 已 登录 的 用 户 是 否 已 经 确认 过 ， 如 果 确 认 过 ， 则 重 定向 到 首页 ， 因 为 很 显然 
此 时 不 用 做 什么 操作 。 这 样 处 理 可 以 避免 用 户 不 小 心 多 次 点 击 确认 令 牌 带 来 的 额外 工作 。 

由 于 令 牌 确认 完全 在 User 模型 中 完成 ， 所 以 视图 函数 只 需 调 用 confirm() 方法 即 可 ， 然 后 
再 根据 确认 结果 显示 不 同 的 内 现 消息 。 确 认 成 功 后 ，User 模型 中 confirmed 属性 的 值 会 被 
修改 并 添加 到 会 话 中 ， 然 后 提交 数据 库 会 话 。 
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各 个 应 用 os ede 比如 ， 人 允许 未 确认 的 用 户 登 
录 ， 但 只 显示 一 个 页 面 ， 要 求 用 户 在 获取 进一步 访问 权限 之 前 先 确认 账户 。 


这 一 步 可 使 用 Flask 提供 的 before_request 钩子 完成 ， 我 们 在 第 2 章 就 已 经 简单 介绍 过 钧 
子 的 相关 内 容 。 对 蓝本 来 说 ，before_request 钩子 只 能 应 用 到 属于 蓝本 的 请 求 上 。 若 想 在 
蓝本 中 使 用 针对 应 用 全 局 请 求 的 钩子 ， 必 须 使 用 before_app_request 装饰 器 。 示 例 8-22 展 
示 如 何 实现 这 个 处 理 程序 。 


示例 8-22 ”app/auth/views.py: 使 用 before_app_request 处 理 程序 过 滤 未 确认 的 账户 


@auth.before_app_request 
def before_request(): 
if current_user.is_authenticated \ 
and not current_user.confirmed \ 
and request.blueprint != 'auth' \ 
and request.endpoint != 'static': 
return redirect(url_for('auth.unconfirmed')) 











@auth.route('/unconfirmed') 
def unconfirmed(): 
if current_user.is_anonymous or current_ user.confirmed: 
return redirect(url_for('main.index')) 
return render_template('auth/unconfirmed.html') 


同时 满足 以 下 3 个 条 件 时 ，before_app_request 处 理 程 序 会 拦截 请 求 。 

(1) 用 户 已 登录 (current_user.is_authenticated 的 值 为 True)。 

(2) 用 户 的 账户 还 未 确认 。 

(3) 请 求 的 URL 不 在 身份 验证 蓝本 中 ， 而 且 也 不 是 对 静态 文件 的 请 求 。 要 赋予 用 户 访问 身 
份 验证 路 由 的 权限 ， 因 为 这 些 路 由 的 作用 是 让 用 户 确 认 账 户 或 执行 其 他 账户 管理 操作 。 

如 果 请 求 满足 以 上 条 件 ， 会 被 重 定 向 到 /auth/unconfirmed 路 由 ， 显 示 一 个 确认 账户 相关 信 

息 的 页 面 。 

































































如 果 before_request 或 before_app_request 的 回调 返回 响应 或 重 定 向 ，Flask 
会 直接 将 其 发 送 至 客户 端 ， 而 不 会 调用 相应 的 视图 函数 。 因 此 ， 这 些 回调 可 
在 必要 时 拦截 请 求 。 























呈现 台 (如 图 8-4 所 示 ) 只 演 染 一 个 模板 ， 其 中 有 如 何 确 认 账 户 的 说 明 ， 
此 外 还 有 一 个 链接 ， 用 于 请 求 发 送 新 的 确认 邮件 ， 以 防 之 前 的 邮件 丢失 。 重 新 发 送 确认 邮 
件 的 路 由 如 示例 8-23 所 示 。 





























@@ MMFlasky -Confirm youraccount x 


€ C 合 @Iocalhost:5000/authyunconfirmed 





Hello, john! 


You have not confirmed your account yet. 


Before you can access this site you need to confirm your account. Check your inbox, you should have received an 
email with a confirmation link. 


Need another confirmation email? Click here 











8-4: 未 确认 账户 页 面 
示例 8-23 app/auth/views.py: 重新 发 送 账 户 确认 邮件 


@auth.route('/confirm') 

@login_required 

def resend_confirmation(): 
token = current_user .generate_confirmation_token() 
send_email(current_ user.email, 'Confirm Your Account', 

'auth/email/confirm', user=current_user, token=token) 

flash('A new confirmation email has been sent to you by email.') 
return redirect(url_for('main.index')) 


这 个 路 由 为 current_user ( 即 已 登录 的 用 户 ， 也 是 目标 用 户 ) 重 做 了 一 遍 注 册 路 由 中 的 操 
作 。 这 个 路 由 也 用 Login_required 保护 ， 确 保 只 有 通过 身份 验证 的 用 户 才 能 再 次 请 求 发 送 
确认 邮件 。 











如 果 你 从 GitHub 上 克隆 了 这 个 应 用 的 Git 仓库 ， 那 么 可 以 执行 git checkout 
8e 检 出 应 用 的 这 个 版 本 。 这 个 版 本 包含 一 个 数据 库 迁移 ， 所 以 检 出 代码 后 别 
忘 了 执行 flask db upgrade 命令 。 








8.7 ”管理 账户 


拥有 应 用 账户 的 用 户 有 时 可 能 需要 修改 账户 信息 。 下 面 这 些 功 能 可 使 用 本 章 介 绍 的 技术 添 
加 到 身份 验证 蓝本 中 。 
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修改 密码 
安全 意识 强 的 用 户 可 能 想 定 期 修改 密码 。 这 是 一 个 很 容易 实现 的 功能 ， 只 要 用 户 处 于 登 
录 状 态 ， 就 可 以 放心 显示 一 个 表单 ， 要 求 用 户 输入 旧 密 码 和 替换 的 新 密码 。 这 个 功能 的 
实现 参见 GitHub 仓库 中 标签 为 8f 的 提交 。 此 次 修改 还 把 导航 栏 中 的 Log Out 链接 改 成 
了 下 拉 菜 单 ， 里 面 有 Change Password 和 Log Out 两 个 链接 。 

重 设 密 码 
为 避免 用 户 忘 记 密 码 后 无 法 登入 ， 应 用 可 以 提供 重 设 密码 功能 。 为 了 安全 起 见 ， 有 必要 
使 用 令 牌 ， 类 似 于 确认 账户 时 用 到 的 。 用 户 请 求 重 设 密码 后 ， 应 用 向 用 户 注册 时 提供 的 
电子 邮件 地 址 发 送 一 封包 含 重 设 令 牌 的 邮件 。 用 户 点 击 邮件 中 的 链接 ， 令 牌 通过 验证 
后 ， 显 示 一 个 用 于 输入 新 密码 的 表单 。 这 个 功能 的 实现 参见 GitHub 仓库 中 标签 为 89 的 
提交 。 

修改 电子 邮件 地 址 
应 用 可 以 提供 修改 注册 电子 邮件 地 址 的 功能 ， 不 过 接受 新 地 址 之 前 ， 必 须 使 用 确认 邮件 
进行 验证 。 使 用 这 个 功能 时 ， 用 户 在 表单 中 输入 新 的 电子 邮件 地 址 。 为 了 验证 新 地 址 ， 
应 用 发 送 一 封包 含 令 牌 的 邮件 。 服 务 器 收 到 令 牌 后 ， 再 更 新 用 户 对 象 。 服 务 器 收 到 令 牌 
之 前 ， 可 以 把 新 电子 邮件 地 址 保存 在 一 个 新 数据 库 字 段 中 作为 待定 地 址 ， 或 者 将 其 与 
id 一 起 保存 在 令 牌 中 。 这 个 功能 的 实现 参见 GitHub 仓库 中 标签 为 8h 的 提交 。 


下 一 章 将 使 用 用 户 角 色 扩 充 Flasky 的 用 户 子 系统 。 
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Web 应 用 中 的 用 户 并 非 都 具有 同等 地 位 。 在 多 数 应 用 中 ， 一 小 部 分 可 信用 户 具 有 额外 权 
限 ， 用 于 保障 应 用 平稳 运行 。 管 理 员 就 是 最 好 的 例子 ,但 有 时 也 需要 介 于 管理 员 和 普通 用 
户 之 间 的 角色 ， 例 如 内 容 协 管 员 。 为 此 ， 要 为 所 有 用 户 分 配 一 个 角色 。 


在 应 用 中 实现 角色 有 多 种 方法 。 有 具体 采用 何 种 实现 方法 取决 于 所 需 角 色 的 数量 和 细 分 程 
度 。 例 如 ， 简 单 的 应 用 可 能 只 需要 两 个 角色 ， 一 个 表示 普通 用 户 ， 一 个 表示 管理 员 。 对 于 
这 种 情况 ， 在 User 模型 中 添加 一 个 is_administrator 布尔 值 字段 可 能 就 够 了 。 复 杂 的 应 
用 可 能 需要 在 普通 用 户 和 管理 员 之 间 再 细 分 出 多 个 不 同等 级 的 角色 。 有 些 应 用 甚至 不 能 使 
用 分 立 的 角色 ， 赋 予 用 户 一 系列 独立 的 权限 或 许 更 合适 。 


本 章 介 绍 的 用 户 角色 实现 方式 结合 了 分 立 的 角色 和 权限 ， 赋 予 用 户 分 立 的 角色 ， 但 是 各 个 
角色 都 通过 权限 列表 定义 允许 用 户 执行 的 操作 。 


9.1 角色 在 数据 库 中 的 表示 


第 5 章 为 了 演示 一 对 多 关系 ， 创 建 了 一 个 简单 的 roles 表 。 示 例 9-1 是 改进 后 的 Role 模型 。 


示例 9-1 app/models.py: 角色 数据 库 模 型 
class Role(db.Model): 
_tablename = 'roles' 
id = db.Column(db.Integer, primary_key=True) 
name = db.Column(db.String(64), unique=True) 
default = db.Column(db.Boolean, default=False, index=True) 
permissions = db.Column(db.Integer) 
users = db.relationship('User', backref='role', lazy='dynamic') 


















































def _ init (self, **kwargs): 
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super(Role, self)._ init (**kwargs) 
if self.permissions is None: 
self.permissions = 0 











这 个 模型 新 增 了 default 字段 。 只 能 有 一 个 角色 的 这 个 字段 可 以 设 为 True， 其 他 角色 都 应 
该 设 为 False。 上 默认 角色 是 注册 新 用 户 时 赋予 用 户 的 角色 。 因 为 应 用 将 在 roles 表 中 搜索 
默认 角色 ， 所 以 我 们 为 这 一 列 设置 了 索引 ， 提 升 搜索 的 速度 。 


这 个 模型 的 另 一 处 改动 是 添加 了 permissions 字段 ， 其 值 是 一 个 整数 ， 以 简洁 的 方式 定义 
一 组 权限 。SQLAlchemy 默认 把 这 个 字段 的 值 设 为 None， 因 此 我 们 添加 了 一 个 类 构造 函 
数 ， 在 未 给 构造 函数 提供 参数 时 ， 把 这 个 字段 的 值 设 为 0。 

显然 ， 各 操作 所 需 的 权限 在 不 同 的 应 用 中 是 不 一 样 的 。 对 Flasky 来 说 ， 各 种 操作 及 其 权限 
如 表 9-1 所 示 。 


表 9-1: 应 用 中 的 各 项 权限 


















































操作 权限 名 权限 值 
关注 用 户 FOLLOW 1 

在 他 人 的 文章 中 发 表 评 论 COMMENT 2 

写 文章 WRITE 4 

管理 他 人 发 表 的 评论 MODERATE 8 

管理 员 权限 ADMIN 16 











使 用 2 的 寡 表 示 权 限 值 有 个 好 处 : 每 种 不 同 的 权限 组 合 对 应 的 值 都 是 唯一 的 ， 方 便 存 入 角 
色 的 permissions 字段 。 例 如 ， 若 想 为 一 个 用 户 角色 赋予 权限 ， 使 其 能 够 关注 其 他 用 户 ， 
并 在 文章 中 发 表 评 论 ， 则 权限 值 为 FOLLOW + COMMENT = 3。 通 过 这 种 方式 存储 各 个 角色 的 
权限 特别 高 效 。 


表 9-1 中 的 权限 可 由 示例 9-2 中 的 代码 对 
示例 9-2 ”app/models.py: 权限 常量 


class Permission: 
FOLLOW = 1 
COMMENT = 2 
WRITE = 4 
MODERATE = 8 
ADMIN = 16 
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添加 这 些 权限 常量 之 后 ， 可 以 在 Role 模型 中 定义 几 个 新 方法 ， 用 于 管理 权限 ， 如 示例 9-3 
所 示 。 


示例 9-3 app/models.py: Role 模型 中 管理 权限 的 方法 
class Role(db.Model): 
i 


def add_permission(self, perm): 
if not self.has_permission(perm): 
self.permissions += perm 





def remove_permission(self, perm): 
if self.has_permission(perm): 
self.permissions -= perm 


def reset_ permissions(self): 
self.permissions = 0 


def has_permission(self, perm): 
return self.permissions & perm == perm 





add_permission()、remove_permission() 和 reset_permission() 这 3 个 方法 使 用 基本 的 算 
术 运 算 符 更 新 权限 列表 。has_permission() 方法 是 这 几 个 方法 中 最 复杂 的 ， 它 使 用 位 与 和 运 
算 符 & (https://docs.python.org/3/reference/expressions.html#binary-bitwise-operations) 检查 


组 合 权 限 是 否 包含 指定 的 单独 权限 。 你 可 以 在 Python shell 中 试 试 这 些 方法 : 


(venv) $ flask shell 

>>> 『 = Role(name='User') 

>>> r.add_permission(Permission.FOLLOW) 
>>> r.add_permission(Permission .WRITE) 

>>> r.has_permission(Permission.FOLLOW) 
True 

>>> r.has_permission(Permission.ADMIN) 

False 

>>> r.reset_permissions() 

>>> r.has_permission(Permission.FOLLOW) 




























































































False 

表 9-2 列 出 了 这 个 应 用 会 支持 的 用 户 角 色 ， 以 及 定义 各 个 角色 的 权限 组 合 

表 9-2: 用 户 角 色 

用 户 角色 权 限 说 明 

匿名 无 对 应 只 读 权 限 ， 这 是 未 登录 的 未 知 用 户 

用 户 FOLLOW、 COMMENT、 WRITE 具有 发 布 文 章 、 发 表 评 论 和 关注 其 他 用 户 的 
权限 ， 这 是 新 用 户 的 默认 角色 

办 管 员 FOLLOW、 COMMENT、 WRITE、 MODERATE 增加 管理 其 他 用 户 所 发 表 评 论 的 权限 

管理 员 FOLLOW、COMMENT、WRITE、MODERATE、ADMIN ” 具有 所 有 权限 ， 包 括 修改 其 他 用 户 所 属 角 色 
的 权限 


将 角色 手动 添加 到 数据 库 中 既 耗 时 又 容易 出 错 。 作 为 替代 ， 我 们 可 以 在 Role 类 中 添加 一 个 
类 方法 ， 完 成 这 个 操作 ， 如 示例 9-4 所 示 。 通 过 这 个 方法 ， 可 以 在 单元 测试 中 轻松 重建 正 
确 的 角色 和 权限 。 当 然 ， 更 重要 的 是 ， 把 应 用 部 署 到 生产 服务 器 上 时 也 可 以 这 么 做 。 


示例 9-4 app/models.py: 在 数据 库 中 创建 角色 
class Role(db.Model): 

# ... 

@staticmethod 

def insert_roles(): 

roles = { 

'User': [Permission.FOLLOW, Permission.COMMENT, Permission.WRITE], 
'Moderator': [Permission.FOLLOW, Permission.COMMENT, 
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Permission.WRITE, Permission.MODERATE], 
'Administrator': [Permission.FOLLOW, Permission.COMMENT, 
Permission.WRITE, Permission.MODERATE, 
Permission.ADMIN], 


default_role = 'User’ 
for r in roles: 
role = Role.query.filter_by(name=r).first() 
if role is None: 
role = Role(name=r) 
role.reset_permissions() 
for perm in roles[r]: 
role.add_permission(perm) 
role.default = (role.name == default_role) 
db.session.add(role) 
db.session.commit() 


insert_roles() 函数 并 不 直接 创建 新 角色 对 象 ， 而 是 通过 角色 名 查找 现 有 的 角色 ， 然 后 再 
进行 更 新 。 只 有 当 数 据 库 中 没有 某 个 角色 名 时 ， 才 会 创建 新 角色 对 象 。 如 此 一 来 ， 如 果 以 
后 更 新 了 角色 列表 ， 就 可 以 执行 更 新 操作 了 。 要 想 添 加 新 角色 ， 或 者 修改 角色 的 权限 ， 修 
改 函 数 顶 部 的 roles 字典 ， 再 运行 这 个 函数 即 可 。 注 意 ,“ 匿 名 ”角色 不 需要 在 数据 库 中 于 
示 出 来 ， 这 个 角色 的 作用 就 是 为 了 表示 不 在 数据 库 中 的 未 知 用 户 。 


此 外 还 要 注意 ，insert_roles() 是 静态 方法 。 这 是 一 种 特殊 的 方法 ， 无 须 创 建 对 象 ， 而 是 
直接 在 类 上 调用 ， 例 如 RoLe.insert_roLes()。 与 实例 方法 不 同 的 是 ， 静 态 方法 的 参数 中 没 
有 self。 


9.2 ”赋予 角色 


用 户 在 应 用 中 注册 账户 时 ， 应 该 赋予 其 适当 的 角色 。 多 数 用 户 在 注册 时 赋予 的 角色 是 “用 
户 ”， 因 为 这 是 默认 角色 。 唯 一 的 例外 是 管理 员 ， 管 理 员 在 最 开始 就 应 该 赋予 “管理 员 ” 
角色 。 管 理 员 由 保存 在 设置 变量 FLASKY_ADMIN 中 的 电子 邮件 地 址 识别 ， 只 要 这 个 电子 邮件 
地 址 出 现在 注册 请 求 中 ， 就 会 被 赋予 正确 的 角色 。 示 例 9-5 展示 了 如 何在 User 模型 的 构造 
函数 中 完成 这 一 操作 。 


示例 9-5 app/models.py: 定义 默认 的 用 户 角 色 
CLass ee db.Model ): 
# 
def _init (self, **kwargs): 
super(User, self).__init_ _(**kwargs) 
if self.role is None: 
if self.email == current_app.config['FLASKY_ADMIN']: 
self.role = Role.query.filter_by(name='Administrator').first() 
if self.role is None: 
self.role = Role.query.filter_by(default=True).first() 
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User 类 的 构造 函数 首先 调用 基 类 的 构造 函数 ， 如 果 创 建 基 类 对 象 后 还 没 定 义 角色 ， 则 根据 
电子 邮件 地 址 决定 将 其 设 为 管理 员 还 是 默认 角色 。 











9.3 检验 角色 


为 了 简化 角色 和 权限 的 实现 过 程 ， 可 在 User 模型 中 添加 一 个 辅助 方法 ， 检 查 赋 了 予 用 户 的 角 
色 是 否 有 某 项 权限 。 这 个 辅助 方法 的 实现 很 简单 ， 直 接 委托 前 面 添加 的 权限 管理 方法 ， 如 
示例 9-6 所 示 。 

示例 9-6 app/models.py: 检查 用 户 是 否 有 指定 的 权限 


from flask_login import UserMixin, AnonymousUserMixin 
































class User(UserMixin, db.Model): 
# ... 


def can(self, perm): 
return self.role is not None and self.role.has_permission(perm) 


def is_administrator(self): 
return self.can(Permission.ADMIN) 


class AnonymousUser(AnonymousUserMixin): 
def can(self, permissions): 
return False 


def is_administrator(self): 
return False 


login_manager .anonymous_User = AnonymousUser 


如 果 角 色 中 包含 请 求 的 权限 ， 那 么 User 模型 中 添加 的 can() 方法 会 返回 True， 表 示人 允 
许 用 户 执行 此 项 操作 。 因 为 经 常 需要 检查 是 否 具 有 管理 员 权 限 ， 所 以 还 单独 实现 了 is_ 
administrator() 方法 。 


为 了 操作 方便 ， 我 们 还 定义 了 AnonymousUser 类 ， 并 实现 了 can() 方法 和 is_administrator() 
方法 。 这 样 ， 应 用 无 须 检查 用 户 是 否 登 录 ， 就 能 放心 调用 current_user.can() 和 current_ 
user .is_administrator()。 我 们 通过 Login_manager.anonymous_user 属性 告诉 Flask-Login 


使 用 应 用 自 定义 的 匿名 用 户 类 。 


如 果 想 让 视图 函数 只 对 具有 特定 权限 的 用 户 开 放 ， 可 以 使 用 自 定义 的 装饰 器 。 示 例 9-7 实 
现 了 两 个 装饰 器 ， 一 个 用 于 检查 常规 权限 ， 另 一 个 专门 检查 管理 员 权限 。 


示例 9-7 app/decorators.py: 检查 用 户 权限 的 自 定义 装饰 器 


from functools import wraps 

from flask import abort 

from flask_login import current_user 
from .models import Permission 


































































































def permission_required(permission): 
def decorator(f): 
@wraps(f) 
def decorated function(*args, **kwargs): 
if not current_uyser.can(permission): 
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abort(403) 
return f(*args, **kwargs) 
return decorated_ function 
return decorator 


def admin_ required(f): 
return permission_ required(Permission.ADMIN)(f) 
这 两 个 修饰 器 都 使 用 了 Python 标准 库 中 的 functools 包 (https://docs.python.org/3/library/ 
functools.html) ， 如 果 用 户 不 具有 指定 权限 ， 则 返回 403 响应 ， 即 HTTP“ 禁 止 ”错误 。 我 
们 在 第 3 章 为 404 和 500 错误 编写 了 自 定 义 的 错误 页 面 ， 所 以 现在 也 要 以 类 似 的 方式 添加 
一 个 403 错误 页 面 。 
下 面 举 两 个 例子 演示 如 何 使 用 这 些 装 饰 器 。 


from .decorators import admin_ required, permission_required 




















@main.route('/admin') 
@login_required 
@admin_required 
def for_admins_only(): 
return "For administrators!" 


@main.route('/moderate') 
@login_required 
@permission_required(Permission.MODERATE) 
def for_moderators_only(): 

return "For comment moderators!" 


根据 经 验 ， 在 视图 函数 上 使 用 多 个 装饰 器 时 ， 应 该 把 Flask 的 route 装饰 器 放 在 首位 。 佘 
下 的 装饰 器 应 该 按照 调用 视图 函数 时 的 执行 顺序 排列 。 以 上 示例 中 应 该 先 检查 用 户 的 身份 
验证 状态 ， 因 为 如 果 发 现 用 户 未 通过 身份 验证 ， 要 将 甚 重 定向 到 登录 页 面 。 


在 模板 中 可 能 也 需要 检查 权限 ， 所 以 Permission 类 的 所 有 常量 要 能 在 模板 中 访问 。 为 了 避 
免 每 次 调用 render_template() 时 都 多 添加 一 个 模板 参数 ， 可 以 使 用 上 下 文 处 理 器 。 在 谊 
染 时 ， 上 下 文 处 理 器 能 让 变量 在 所 有 模板 中 可 访问 。 修 改 方法 如 示例 9-8 所 示 。 
示例 9-8 app/main/_init .py: 把 Permission 类 加 入 模板 上 下 文 

@main.app_context_processor 

def inject_ permissions(): 

return dict(Permission=Permission) 

新 添加 的 角色 和 权限 可 在 单元 测试 中 进行 测试 ， 示例 9-9 是 其 中 两 个 测试 。GitHub 中 的 源 
码 为 每 个 角色 都 编写 了 一 个 测试 。 
示例 9-9 tests/test_user_ model.py: 角色 和 权限 的 单元 测试 


class UserModelTestCase(unittest.TestCase): 
ns 























def test user_role(self): 
uU = User(email='john@example.com', password='cat') 
self.assertTrue(uy.can(Permission.FOLLOW)) 
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self.assertTrue(y.can(Permission.COMMENT)) 
self.assertTrue(y.can(Permission.WRITE)) 
self.assertFalse(u.can(Permission.MODERATE)) 
self.assertFalse(u.can(Permission.ADMIN)) 


def test_anonymous_User(seLf) : 
U = AnonymousUser() 
self.assertFalse(y.can(Permission.FOLLOW)) 
self.assertFalse(y.can(Permission.COMMENT)) 
self.assertFalse(u.can(Permission.WRITE)) 
self.assertFalse(u.can(Permission.MODERATE)) 
self.assertFalse(u.can(Permission.ADMIN)) 

















执行 flask db upgrade 命令 。 








阅读 下 一 章 之 前 ， 在 shell 会 话 中 把 这 些 新 角色 添加 到 开发 数据 库 中 : 


(venv) $ flask shell 

>>> Role.insert_roles() 

>>> Role.query.all() 

[<Role 'Administrator'>, <Role 'User'>, <Role 'Moderator'>] 


如 果 你 从 GitHub 上 克隆 了 这 个 应 用 的 Git 仓库 ， 那 么 可 以 执行 git checkout 
9a 检 出 应 用 的 这 个 版 本 。 这 个 版 本 包含 一 个 数据 库 迁 移 ， 检 出 代码 后 记得 


此 外 ， 最 好 更 新 用 户 列 表 ， 为 在 此 之 前 创建 的 用 户 账户 分 配 用 户 角 色 。 这 个 操作 可 通过 在 


Python shell 中 执行 下 述 代 码 完成 : 
(venv) $ flask shell 


>>> admin_role = Role.query.filter_by(name="'Administrator').first() 


>>> default_role = Role.query.filter_by(default=True).first() 
>>> for U in User.query.all(): 
if uy.role is None: 
if u.email == app.config['FLASKY_ADMIN']: 
u.role = admin_role 
else: 
u.role = default_role 


>>> db.session.commit() 





现在 ， 用 户 系统 基本 完成 了 。 下 一 章 将 利用 这 个 系统 创建 用 户 资 料 页 面 








o 
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用 户 资 料 





























本 章 将 为 Flasky 实现 用 户 资料 页 面 。 所 有 社交 网 站 都 会 给 用 户 提供 资料 页 面 ， 简 要 显示 用 
户 在 网 站 中 的 活动 情况 。 用 户 可 以 把 资料 页 面 的 URL 分 享 给 别人 ， 告 诉 别人 自己 在 这 个 
网 站 上 。 因 此 ， 这 个 页 面 的 URL 要 简短 易 记 。 


10.1 资料 信息 


为 了 让 用 户 的 资料 页 面 更 吸引 人 ， 可 以 在 数据 库 中 存储 用 户 的 一 些 额 外 信息 。 示 例 10-1 扩 
充 了 User 模型 ， 添 加 了 几 个 新 字段 。 


示例 10-1 app/models.py: 用 户 信息 字段 
class User(UserMixin, db.Model): 
# .有 
name = db.Column(db.String(64)) 
location = db.Column(db.String(64)) 
about_ me = db.Column(db.Text()) 
member_since = db.Column(db.DateTime(), default=datetime.utcnow) 
Last_seen = db.Column(db.DateTime(), default=datetime.utcnow) 


新 添加 的 字段 保存 用 户 的 真实 姓名 、 所 在 地 、 自 我 介绍 、 注 册 日 期 和 最 后 访问 日 期 。 
about_me 字段 的 类 型 是 db.Text()。db.String 和 db.Text 的 区 别 在 于 后 者 是 变 长 字段 ， 因 
此 不 需要 指定 最 大 长 度 。 


两 个 时 间 惟 的 默认 值 都 是 当前 时 间 。 广 意 ，datetime.utcnow 后 面 没有 ()， 因 为 db.Column() 
的 default 参数 可 以 接受 国 数 作为 默认 值 ， 每 次 需要 生成 默认 值 时 ，SQLAlchemy 都 会 调 
用 指定 的 函数 。member_since 字段 使 用 默认 值 即 可 。 


Last_seen 字段 的 默认 值 也 是 创建 时 的 当前 时 间 ， 但 用 户 每 次 访问 网 站 后 ， 这 个 值 都 要 刷 
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新 。 我 们 可 以 在 User 类 中 添加 一 个 方法 执行 这 个 操作 ， 如 示例 10-2 所 示 。 
示例 10-2 app/models.py: 刷新 用 户 的 最 后 访问 时 间 


class User(UserMixin, db.Model): 
# ... 


def ping(self): 
self.last_seen = datetime.utcnow() 
db.session.add(self) 
db.session.commit() 


为 了 确保 每 个 用 户 的 最 后 访问 时 间 都 是 最 新 的 ， 每 次 收 到 用 户 的 请 求 时 都 要 调用 ping() 方 
法 。 因 为 auth 蓝本 中 的 before_app_request 处 理 程序 会 在 每 次 请 求 前 运行 ， 所 以 能 很 轻 
松 地 实现 这 个 需求 ， 如 示例 10-3 所 示 。 


示例 10-3 app/auth/views.py: 更 新 已 登录 用 户 的 最 后 访问 时 间 
@auth.before_app_request 
def before_request(): 
if current_user.is _ authenticated: 
current_user .ping() 
if not current_user.confirmed \ 
and request.endpoint \ 
and request.blueprint != 'auth' \ 
and request.endpoint != 'static': 
return redirect(url_for('auth.unconfirmed')) 


10.2 用户 资料 页 面 
为 每 个 用 户 创建 资料 页 面 并 没有 什么 难度 。 示 例 10-4 是 路 由 定义 。 
示例 10-4 ”app/main/views.py: 资料 页 面 的 路 由 


@main.route('/user/<username>') 

def user(username): 
user = User.query.filter_by(username=username).first_or_404() 
return render_template('user.html', user=user) 


这 个 路 由 添加 到 main 蓝本 中 。 对 于 名 为 john 的 用 户 ， 其 资料 页 面 的 地 址 是 http:// 
localhost:5000/user/john。 这 个 视图 函数 会 在 数据 库 中 搜索 URL 中 指定 的 用 户 名 ， 如 果 找 
到 ， 则 渲染 模板 user.html， 并 把 用 户 名 作为 参数 传 入 模板 。 如 果 传 入 路 由 的 用 户 名 不 存 
在 ， 则 返回 404 错误 。 使 用 Flask-SQLAlchemy 时 ， 搜 到 结果 和 返回 错误 这 两 种 情况 可 以 
在 同一 个 语句 中 表达 ， 即 在 查询 对 象 上 调用 first_or_404() 方法 。user.html 模板 用 于 呈现 
用 户 信息 ， 因 此 要 把 用 户 对 象 作为 参数 传人 其 中 。 这 个 模板 的 初始 版 本 如 示例 10-5 所 示 。 


示例 10-5 app/templates/user.html: 用 户 资料 页 面 的 模板 


{% extends "base.html" %} 
{% block title %}Flasky - {{ user.username }}{% endblock %} 







































































{% block page_content %} 
<div class="page-header"> 




















</di 
{% e 


<h1i>{{ user.username }}</h1> 
{% if user.name or user.location %} 
<p> 

{% if user.name %}{{ user.name }}{% endif %} 

{% if user.location %} 

From <a href="http://maps.google.com/?q={{ user.location }}"> 
{{ user.location }} 
</a> 

{% endif %} 
</p> 
{% endif %} 
{% if current_user.is_administrator() %} 
<p><a href="mailto:{{ user.email }}">{{ user.email }}</a></p> 
{% endif %} 
{% if user.about me %}<p>{{ user.about me }}</p>{% endif %} 
<p> 

Member since {{ moment(user.member_since).format('L') }}. 

Last seen {{ moment(user.last_ seen).fromNow() }}. 
</p> 
V> 
ndblock %} 


在 这 个 模板 中 ， 有 几 处 实现 细 广 需要 说 明 一 下 。 


。 name 和 Location 字段 在 同一 个 <p> 元 素 中 演 染 。Jinja2 条 件 语句 确保 ， 仅 当 至 少 定义 了 
这 两 个 字段 中 的 一 个 时 ， 才 会 创建 <p> 元 素 。 





。 用 户 的 location 字段 被 泻 染 成 指向 谷歌 地 图 的 查询 链接 ， 点 击 打开 后 将 显示 一 个 地 图 ， 





























以 所 标 位 置 为 中 心 。 


。 如 果 登 录 的 用 户 是 管理 员 ， 显 示 各 用 户 的 : 




















于 管理 员 查 看 用 户 资料 页 面 并 联系 该 用 户 。 
。 两 个 时 间 惟 使 用 Flask-Moment 泻 染 (参见 第 3 章 )。 


多 数 用 户 都 希望 能 轻松 找到 自己 的 资料 页 面 ， 因 此 我 们 可 以 在 导航 栏 中 添加 一 个 链接 。 对 


base.html 














模板 所 做 的 修改 如 示例 10-6 所 示 。 


示例 10-6 ”app/templates/base.html: 在 导航 栏 中 添加 指向 资料 页 面 的 链接 


{% if current_user.is_authenticated %} 


<li> 


<a href="{{ url_for('main.user', username=current_uyser.username) }}"> 


Profile 
</a> 


</li> 
{% endif %} 


把 资料 页 面 的 链接 包含 在 条 件 语 句 中 是 非常 必要 的 ， 因 为 未 通过 身份 验证 的 用 户 也 能 看 到 


样子 。 图 















































中 还 显示 了 刚 在 导航 栏 里 添加 的 资料 页 面 链接 。 


但 我 们 不 应 该 让 他 们 看 到 资料 页 面 的 链接 。 图 10-1 展示 了 资料 页 面 在 浏 


[Ue 


唤 合 











电子 邮件 地 址 ， 且 泻 染 成 mailto 链接 。 这 样 便 


中 的 
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@e 六 Flasky -john 


< GO © localhost:500 





John Smith from Portland, OR 
Python aficionado. 


Member since 07/23/2017. Last seen a few seconds ago. 














10-1: 用 户 资料 页 面 


如 果 你 从 GitHub 上 克隆 了 这 个 应 用 的 Git 仓库 ， 那 么 可 以 执行 gtt checkout 
10a 检 出 应 用 的 这 个 版 本 。 这 个 版 本 包含 一 个 数据 库 迁 移 ， 检 出 代码 后 记得 
执行 fLask db upgrade 命令 。 














10.3 资料 编辑 器 


用 户 资料 的 编辑 分 两 种 情况 。 最 显而易见 的 情况 是 ， 用 户 要 进入 一 个 页 面 ， 输 入 自己 的 资 
料 ， 以 便 显示 在 自己 的 资料 页 面 上 。 还 有 一 种 不 太 明 显 但 也 同样 重要 的 情况 ， 那 就 是 要 让 
管理 员 能 够 编辑 任意 用 户 的 资料 一 一 不 仅 要 能 编辑 用 户 的 个 人 信息 ， 还 要 能 编辑 用 户 不 能 
直接 访问 的 User 模型 字段 ， 例 如 用 户 角色 。 这 两 种 编辑 需求 有 本 质 上 的 区 别 ， 所 以 我 们 将 
创建 两 个 不 同 的 表单 。 


10.3.1 用 户 级 资料 编辑 器 
普通 用 户 的 资料 编辑 表单 如 示例 10-7 所 示 。 


示例 10-7 ”app/main/forms.py: 资料 编辑 表单 
class EditprofileForm(FlaskForm): 
name = StringField('Real name', validators=[Length(0, 64)]) 
location = StringField('Location', validators=[Length(0, 64)]) 
about_me = TextAreaField('About me') 
submit = SubmitField('Submit') 


注意 ， 这 个 表单 中 的 所 有 字段 都 是 可 选 的 ， 因 此 长 度 验证 函数 的 最 小 值 为 零 。 显 示 这 个 表 
单 的 路 由 定义 如 示例 10-8 所 示 。 











ie 


























示例 10-8 app/main/views.py: 资料 编辑 路 由 
@main.route('/edit-profile', methods=['GET', 'POST']) 
@login_required 
def edit profile(): 

form = EditprofileForm() 

if form.validate on_submit(): 
current_user .name = form.name.data 
current_user.location = form.Location.data 
current_user.about me = form.about_me.data 
db.session.add(current_user._ get current object()) 
db.session.commit() 
flash('Your profile has been updated.') 
return redirect(url_for('.user', Username=current_user .username)) 

form.name.data = current_user.name 

form.Location.data = current_user.location 

form.about me.data = current user.about me 

return render_template('edit profile.html', form=form) 


与 之 前 的 表单 一 样 ， 各 表单 字段 中 的 数据 使 用 form.<field-name>.data 获取 。 通 过 这 
个 表达 式 不 仅 能 获取 用 户 提交 的 值 ， 还 能 在 字段 中 显示 初始 值 ， 供 用 户 编辑 。 当 form. 
validate_on_submit() 返回 False 时 ， 表 单 中 的 3 个 字段 都 使 用 current_user 中 保存 的 初 
始 值 。 提 交 表 单 后， 表单 字段 的 data 属性 中 保存 有 更 新 后 的 值 ， 因 此 可 以 将 其 赋值 给 用 户 
对 象 中 的 各 字段 ， 然 后 再 把 用 户 对 象 存 人 数据 库 。 编 辑 资料 页 面 如 图 10-2 所 示 。 
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@@ MM Fasky- EditProfile x 


€ CO © localhost:5000/edit-profile 





Edit Your Profile 


Real name 


John Smith 


Location 


Portland, OR 


About me 


Python aficionado. 


Submit 














10-2: 资料 编辑 器 





为 了 让 用 户 能 轻松 找到 编辑 页 面 ， 我 们 可 以 在 资料 页 面 中 添加 一 个 链接 ， 如 示例 10-9 所 示 。 
示例 10-9 ”app/templates/user.html: 资料 编辑 页 面 的 链接 


{% if user == current_user %} 

<a class="btn btn-default" href="{{ url_for('.edit profile') }}"> 
Edit Profile 

</a> 

{% endif %} 


链接 外 层 的 条 件 语 句 能 确保 只 有 当 用 户 查看 自己 的 资料 页 面 时 才 显示 这 个 链接 。 


10.3.2 ”管理 员 级 资料 编辑 器 


管理 员 使 用 的 资料 编辑 表单 比 普 通用 户 的 表单 更 加 复杂 。 除 了 前 面 的 3 个 资料 信息 字段 之 
外 ， 管 理 员 在 表单 中 还 要 能 编辑 用 户 的 电子 邮件 、 用 户 名 、 确 认 状 态 和 和 角色。 这 个 表单 如 
示例 10-10 所 示 。 


示例 10-10 app/main/forms.py: 管理 员 使 用 的 资料 编辑 表单 
class EditprofileAdminForm(FlaskForm): 
email = StringField('Email', validators=[DataRequired(), Length(1, 64), 
Email()]) 

Username = StringField('Username', validators=[ 
DataRequired(), Length(1, 64), 
Regexp('^[A-Za-z][A-Za-z0-9_.]*$', 0, 

"Usernames must have only letters, numbers, dots or 
'underscores')]) 

confirmed = BooleanField('Confirmed') 

role = SelectField('Role', coerce=int) 

name = StringField('Real name', validators=[Length(0, 64)]) 

Location = StringField('Location', validators=[Length(0, 64)]) 

about_me = TextAreaField('About me') 

submit = SubmitField('Submit') 

































































def _ init (self, user, *args, **kwargs): 
super(EditprofileAdminForm, self). init (*args, **kwargs) 
self.role.choices = [(role.id, role.name) 
for role in Role.query.order_by(Role.name).all()] 
self.user = User 


def validate email(self, field): 
if field.data != self.user.email and \ 
User .query.filter_by(email=field.data).first(): 
raise ValidationError('Email already registered.') 


def validate username(self, field): 
if field.data != self.user.username and \ 
User .query.filter_by(username=field.data).first(): 
raise ValidationError('Username already in use.') 











SelectField 是 WTForms 对 HTML 表单 控件 <select> 的 包装 ， 功 能 是 实现 下 拉 列 表 ， 这 
个 表单 中 用 于 选择 用 户 角 色 。SelectField 实例 必须 在 其 choices 属性 中 设置 各 选项 。 选 项 
必须 是 一 个 由 元 组 构成 的 列表 ， 各 元 组 都 包含 两 个 元 素 : 选项 的 标识 符 ， 以 及 显示 在 控件 









































中 的 文本 字符 串 。choices 列表 在 表单 的 构造 函数 中 设 定 ， 其 值 从 Role 模型 中 获取 ， 使 用 
一 个 查询 按照 角色 名 的 字母 顺序 排列 所 有 角色 。 元 组 中 的 标识 符 是 角色 的 id， 因 为 这 是 个 
整数 ， 所 以 在 SelectField 构造 函数 中 加 上 了 coerce=int 参数 ， 把 字段 的 值 转换 为 整数 ， 
而 不 使 用 默认 的 字符 串 。 


email 和 user 


























nane 字段 的 构造 方式 与 身份 验证 表单 中 的 一 样 ， 但 处 理 验证 时 需要 更 加 小 心 。 








验证 这 两 个 字段 时 ， 首 先 要 检查 字段 的 值 是 否 发 生 了 变化 : 仅 当 有 变化 时 ， 才 要 保证 新 值 
不 与 其 他 用 户 的 相应 字段 值 重 复 ， 如 果 字 段 值 没有 变化 ， 那 么 应 该 跳 过 验证 。 为 了 实现 这 
个 逻辑 ， 表 单 构造 国 数 接收 用 户 对 象 作为 参数 ， 并 将 其 保存 在 成 员 变量 中 ， 供 后 面 自 定义 
的 验证 方法 使 用 。 


管理 员 的 资料 编辑 器 路 由 定义 如 示例 10-11 所 示 。 


























示例 10-11 


from ..d 


@main.ro 
@login_r 
@admin_r 
def edit 
user 
form 
1f.f 


form. 
form. 
form. 
form. 
form. 
form. 
form. 


retu 





























app/main/views.py: 管理 员 的 资料 编辑 路 由 
ecorators import admin_required 
ute('/edit-profile/<int:id>', methods=['GET', 'POST']) 


equired 
equired 


_profile_admin(id): 


= User .query.get or_404(id) 

= EditprofileAdminForm(user=user) 
orm.validate_on_submit(): 

user.email = form.email.data 

user.username = form.username.data 
user.confirmed = form.confirmed.data 
User.role = Role.query.get(form.role.data) 
user .name = form.name.data 

user.location = form.location.data 
user.about me = form.about me.data 
db.session.add(user) 

db.session.commit() 

flash('The profile has been updated.') 
return redirect(url_for('.user', username=user .username)) 
email.data = user.email 

Username .data = User.Username 
confirmed.data = user.confirmed 

role.data = user.role _id 

name.data = User.name 

Location.data = User.Location 
about_me.data = User.about_me 

rn render_template('edit profile.html', form=form, user=user) 


这 个 路 由 与 普通 用 户 的 那个 相对 简单 的 编辑 路 由 具有 基本 相同 的 结构 ， 只 不 过 多 了 个 admin_ 
required 装饰 器 (在 第 9 章 定义 )， 当 非 管理 员 尝 试 访问 这 个 路 由 时 ， 它 会 自动 返回 403 错误 。 
用 户 id 由 URL 中 的 动态 参数 指定 ， 因 此 可 使 用 Flask-SQLAIchemy 提供 的 get_or_404() 
函数 ， 在 提供 的 id 不 正确 时 返回 404 错误 。 我 们 还 需要 再 探讨 一 下 用 于 选择 用 户 角色 的 


SelectField, 


























设 定 这 个 字段 的 初始 值 时 ，role_id 被 赋值 给 了 form.role.data， 这 么 做 的 原因 在 

















于 choices 属性 中 设置 的 元 组 列表 使 用 数字 标识 符 表示 各 选项 。 表 单 提交 后 ，id 从 字段 的 data 





属性 中 提取 ， 


并 且 查 询 时 会 使 用 提取 出 来 的 id 值 加 载 角色 对 象 。 表 单 中 声明 selectField 时 
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设 定 的 coerce=int 参数 ， 其 作用 是 保证 这 个 字段 的 data 属性 值 始终 被 转换 成 整数 。 
为 链接 到 这 个 页 面 ， 我 们 还 需 在 用 户 资料 页 面 中 添加 一 个 按钮 ， 如 示例 10-12 所 示 。 
示例 10-12 ”app/templates/user.html: 管理 员 使 用 的 资料 编辑 页 面 链 接 


{% if current user.is administrator() %} 
<a class="btn btn-danger" 
href="{{ url_for('.edit profile admin', id=user.id) }}"> 
Edit Profile [Admin] 
</a> 
{% endif %} 


为 了 醒目 ， 这 个 按钮 使 用 了 不 同 的 Bootstrap 样式 进行 浑 染 。 外 层 的 条 件 语句 确保 只 有 当前 
登录 的 用 户 为 管理 员 角 色 时 才 显 示 按 钮 。 











如 果 你 从 GitHub 上 克隆 了 这 个 应 用 的 Git 仓库 ， 那 么 可 以 执行 git checkout 
19b 检 出 应 用 的 这 个 版 本 。 











10.4 用 户头 像 


为 了 进一步 改进 资料 页 面 的 外 观 ， 可 以 在 页 面 中 显示 用 户 的 头像 。 在 本 节 ， 你 将 学 到 如 何 
添加 Gravatar 提供 的 用 户头 像 。Gravatar 是 一 个 行业 领先 的 头像 服务 ， 能 把 头像 和 电子 邮 
件 地 址 关联 起 来 。 用 户 要 先 到 https://en.gravatar.com/ 中 注册 账户 ， 然 后 上 传 图 像 。 这 个 服 
务 通过 一 个 特殊 的 URL 对 外 开放 用 户 的 头像 ， 这 个 URL 中 包含 用 户 电子 邮件 地 址 的 MD5 
散 列 值 ， 计 算 方法 如 下 : 

(venv) $ python 

>>> import hashlib 


>>> hashlib.md5('john@example.com' .encode('utf-8')).hexdigest() 
'd4c74594d841139328695756648b6bd6' 


生成 的 头像 URL 是 在 https://secure.gravatar.com/avatar/ 之 后 加 上 这 个 MD5 散 列 值 。 例 
如 ， 你 在 六 览 器 的 地 址 栏 中 输入 https://secure.gravatar.com/avatar/d4c74594d8411393286- 
95756648b6bd6 后 ， 将 看 到 电子 邮件 地 址 john@example.con 对 应 的 头像 。 如 果 这 个 电子 邮 
件 地 址 没有 关联 头像 ， 则 会 显示 一 个 默认 图 像 。 得 到 基本 的 头像 URL 之 后 ， 还 可 以 添加 
一 些 查询 字符 串 参 数 ， 配 置 头 像 的 特征 。 可 设 参数 如 表 10-1 所 示 。 


表 10-1: Gravatar 查 询 字符 串 参 数 

















































































































参数 名 说 明 

s 图 像 尺寸 ， 单 位 为 像素 

图 像 级 别 ， 可 选 值 有 "9"、"pg"、"r" 和 "x" 

d 尚未 注册 Gravatar 服务 的 用 户 使 用 的 默认 图 像 生成 方式 ， 可 选 值 有 : "464"， 返 下 
404 错误 ， 一 个 URL， 指 向 默认 图 像 ， 某 种 图 像 生成 方式 ， 包 括 "mm"、"identicon"、 
"monsterid"、"wavatar"、"retro" 和 "blank" 

fd 强制 使 用 默认 头像 




















例如 ， 在 john@example.com 的 头像 URL 后 加 上 ?d=identicon， 默 认 头 像 将 变 成 几何 图 形 。 
头像 URL 的 这 些 参数 都 可 以 添加 到 User 模型 中 ， 具 体 实现 如 示例 10-13 所 示 。 


示例 10-13 app/models.py: 生成 Gravatar URL 


import hashlib 
from flask import request 








class User(UserMixin, db.Model): 
ns 
def gravatar(self, size=100, default='identicon', rating='g'): 
url = 'https://secure.gravatar .com/avatar’ 
hash = hashlib.mds(self.email.lower().encode('utf-8')).hexdigest() 
return '{url}/{hash}?s={size}&d={default}&r={rating}' .format( 
url=url, hash=hash, size=size, default=default, rating=rating) 


头像 的 URL 由 基 URL、 用 户 电子 邮件 地 址 的 MD5 散 列 值 和 参数 组 成 ， 而 且 各 个 参数 都 有 
默认 值 。 注 意 ，Gravatar 要 求 在 计算 MD5 散 列 值 时 要 规范 电子 邮件 地 址 ， 把 字母 全 部 转换 
成 小 写 ， 因 此 这 个 方法 也 添加 了 这 一 步 。 有 了 上 述 实现 ， 我 们 就 可 以 在 Python shell 中 轻 
公 生 成 头像 的 URL 了 : 

(venv) $ fLask shell 

>>> U = User(email='john@example.conm') 

>>> U.gravatar() 

'https://secure.gravatar .com/avatar/d4c74594d841139328695756648b6bd6?s=100&d= 

identicon&r=g' 

>>> Uy.gravatar(size=256) 


'https://secure.gravatar .com/avatar/d4c74594d841139328695756648b6bd6?s=256&d= 
identicon&r=g' 


gravatar() 方法 也 可 在 Jinja2 模板 中 调用 。 示 例 10-14 在 资料 页 面 中 添加 一 个 大 小 为 256 
像素 的 头像 。 


示例 10-14 ”app/tempaltes/user.html: 在 资料 页 面 中 添加 头像 


























<img class="img-rounded profile-thumbnail" src="{{ user.gravatar(size=256) }}"> 
<div class="profile-header"> 


</div> 





profile-thumbnail 这 个 CSS 类 用 于 定位 图 像 在 页 面 中 的 位 置 。 头 像 后 面 的 <div> 元 素 把 
资料 信息 包围 起 来 ， 通 过 CSS profile-header 类 改进 格式 。 这 两 个 CSS 类 的 定义 参见 本 
应 用 的 GitHub 仓库 。 


使 用 类 似 的 方式 ， 我 们 可 在 基 模板 的 导航 栏 中 添加 一 个 已 登录 用 户头 像 的 小 型 缩 略图 。 为 
了 更 好 地 调整 页 面 中 头像 图 片 的 显示 格式 ， 我 们 可 使 用 一 些 自 定义 的 CSS 类 。 你 可 以 在 源 
码 仓库 的 styles.css 文件 中 查看 自 定 义 的 CSS。styles.css 文件 保存 在 应 用 的 静态 文件 目录 
中 ， 在 base.html 模板 中 引入 应 用 。 图 10-3 是 显示 有 头像 的 用 户 资料 页 面 。 
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©9 六 Flasky -john 


€ CO © localhost:5000/user/johr 





John Smith 
from Portland, OR 
Python aficionado. 


Member since 07/23/2017. Last seen a few seconds ago. 


Edit Profile 











图 10-3: 显示 有 头像 的 用 户 资料 页 面 





如 果 你 从 GitHub 上 克隆 了 这 个 应 用 的 Git 仓库 ， 那 么 可 以 执行 git checkout 
16c 检 出 应 用 的 这 个 版 本 。 











生成 头像 时 要 生成 MD5 散 列 值 ， 这 是 一 项 CPU 密集 型 操作 。 如 果 要 在 某 个 页 面 中 生成 大 
量 头 像 ， 计 算 量 会 非常 大 。 只 要 电子 邮件 地 址 不 变 ， 对 应 的 MD5 散 列 值 就 不 会 变 。 鉴 于 
此 ， 我 们 可 以 将 其 缓存 在 User 模型 中 。 若 要 把 MD5 散 列 值 保存 在 数据 库 中 ， 需 要 对 User 
模型 做 些 改动 ， 如 示例 10-15 所 示 。 


示例 10-15 app/models.py: 使 用 缓存 的 MD5 散 列 值 生成 Gravatar URL 
class User(UserMixin, db.Model): 
# 
avatar_hash = db.Column(db.String(32)) 














def _ init (self, **kwargs): 
i 
if self.email is not None and self.avatar_hash is None: 
self.avatar_hash = self.gravatar_hash() 


def change_ email(self, token): 
Hs 
self.email = new_email 
self.avatar_hash = self.gravatar_hash() 
db.session.add(self) 























return True 


def gravatar_hash(self): 
return hashLib.md5(seLf.emaiL.Lower().encode('utf-8' )).hexdigest() 


def gravatar(self, size=100, default='identicon', rating='g'): 

if request.is_secure: 
url = 'https://secure.gravatar .com/avatar' 

else: 
url = 'http://www.gravatar .Com/avatar' 

hash = self.avatar_hash or self.gravatar_hash() 

return '{url}/{hash}?s={size}&d={default}&r={rating}' .format( 
url=url, hash=hash, size=size, default=default, rating=rating) 


为 了 避免 重复 编写 计算 Gravatar 散 列 值 的 逻辑 ， 我 们 专门 定义 了 gravatar_hash() 方法 执 
行 此 项 任务 。 模 型 初始 化 时 ， 散 列 值 存储 在 新 增 的 avatar_hash 属性 中 。 如 果 用 户 更 新 了 
电子 邮件 地 址 ， 则 重新 计算 散 列 值 。 如 果 存 储 了 散 列 值 ，gravatar() 方法 将 使 用 存储 的 
值 ， 否 则 将 按照 之 前 的 方式 计算 散 列 值 。 


如 果 你 从 GitHub 上 克隆 了 这 个 应 用 的 Git 仓库 ， 那 么 可 以 执行 gtt checkout 
16d 检 出 应 用 的 这 个 版 本 。 这 个 版 本 中 包含 了 一 个 数据 库 迁 移 ， 检 出 代码 后 
记得 要 运行 flask db upgrade 命令 。 


























下 一 章 将 创建 驱动 这 个 应 用 的 博客 引擎 。 
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博客 文章 





本 章 将 实现 Flasky 的 主要 功能 ， 即 允许 用 户 阅 读 和 撰写 博客 文章 。 本 章 将 教 你 一 些 新 技 
术 : 重用 模板 、 分 页 显示 长 列表 ， 以 及 处 理 富 文本 。 


11.1 提交 和 显示 博客 文章 
为 支持 博客 文章 ， 我 们 需要 创建 一 个 新 的 数据 库 模 型 ， 如 示例 11-1 所 示 。 


示例 11-1 app/models.py: Post 模型 


class Post(db.Model): 
_tablename _ = 'posts' 
id = db.Column(db.Integer, primary_key=True) 
body = db.Column(db.Text) 
timestamp = db.Column(db.DateTime, index=True, default=datetime.utcnow) 
author_id = db.Column(db.Integer, db.ForeignKey('users.id')) 











class User(UserMixin, db.Model): 
# ... 
posts = db.relationship('Post', backref='author', lazy='dynamic') 
博客 文章 包含 正文 、 时 间 惟 以 及 和 User 模型 之 间 的 一 对 多 关系 。body 字段 的 类 型 是 
db.Text， 所 以 不 限制 长 度 。 
应 用 的 首页 要 显示 一 个 表单 ， 让 用 户 撰写 博客 。 这 个 表单 很 简单 ， 只 包括 一 个 多 行文 本 输 
入 框 ， 用 于 输入 博客 文章 的 内 容 ， 另 外 还 有 一 个 提交 按钮 。 表 单 定义 如 示例 11-2 所 示 。 


示例 11-2 ”app/main/forms.py: 博客 文章 表单 


class PostForm(FlaskForm): 
body = TextAreaField("What's on your mind?", validators=[DataRequired()]) 
submit = SubmitField('Submit') 
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index() 视图 函数 处 理 这 个 表单 并 把 以 前 发 布 的 博客 文章 列表 传 给 模板 ， 如 示例 11-3 所 示 。 


示例 11-3 ”app/main/views.py: 处 理 博客 文章 的 首页 路 由 
@main.route('/', methods=['GET', 'POST']) 
def index(): 
form = PostForm() 
if current_user.can(Permission.WRITE_ARTICLES) and form.validate_on_submit(): 
post = Post(body=form.body.data, 
author=current_user._get current object()) 
db.session.add(post) 
db.session.commit() 
return redirect(url_for('.index')) 
posts = Post.query.order_by(Post.timestamp.desc()).all() 
return render_template('index.html', form=form, posts=posts) 


这 个 视图 函数 把 表单 和 完整 的 博客 文章 列表 传 给 模板 。 文 章 列 表 按 照 时 间 惟 进行 降序 排 
列 。 博 客 文章 表单 采取 惯常 处 理 方式 ， 如 果 提 交 的 数据 能 通过 验证 ， 就 创建 一 个 新 Post 实 
例 。 在 发 布 新 文章 之 前 ， 要 检查 当前 用 户 是 否 有 写 文章 的 权限 。 


注意 ， 新 文章 对 象 的 author 属性 值 为 表达 式 current_user._get_current_object()。 变 量 
current_user 由 Flask-Login 提供 ， 与 所 有 上 下 文 变量 一 样 ， 也 是 实现 为 线程 内 的 代理 对 
象 。 这 个 对 象 的 表现 类 似 用 户 对 象 ， 但 实际 上 却 是 一个 轻 度 包装 ， 包含 真正 的 用 户 对 象 。 
数据 库 需要 真正 的 用 户 对 象 ， 因 此 要 在 代理 对 象 上 调用 _get_current_object() 方法 。 


这 个 表单 显示 在 index.html 模板 中 的 欢迎 消息 下 方 ， 其 后 是 博客 文章 列表 。 这 是 我 们 首次 
尝试 实现 博客 文章 时 间 轴 ， 按 时 间 顺 序 由 新 到 有 旧 列 出 数据 库 中 所 有 的 博客 文章 。 对 模板 所 
做 的 改动 如 示例 11-4 所 示 。 


示例 11-4 app/templates/index.html: 显示 博客 文章 的 首页 模板 
{% extends "base.html" %} 
{% import "bootstrap/wtf.html" as wtf %} 







































































<div> 
{% if current_user.can(Permission.WRITE_ARTICLES) %} 
{{ wtf.quick_form(form) }} 
{% endif %} 
</div> 
<ul class="posts"> 
{% for post in posts %} 
<li class="post"> 
<div class="profile-thumbnail"> 
<a href="{{ url_for('.user', Username=post.author.username) }}"> 
<img class="img-rounded profile-thumbnail" 
src="{{ post.author .gravatar(size=40) }}"> 
</a> 
</div> 
<div class="post-date">{{ moment(post.timestamp).fromNow() }}</div> 
<div class="post-author"> 
<a href="{{ url_for('.user', username=post.author.username) }}"> 
{{ post.author.username }} 
</a> 
</div> 





<div class="post-body">{{ post.body }}</div> 
</li> 
{% endfor %} 
</ul> 


注意 ， 如 果 用 户 所 属 角色 没有 WRITE 权限 ， 经 User .can() 方法 检查 后 ， 不 会 显示 博客 文章 
表单 。 博 客 文章 列表 通过 HTML 无 序列 表 实 现 ， 并 指定 了 一 个 CSS 类， 从 而 让 格式 更 精 
美 。 页 面 左 侧 会 显示 作者 的 小 头像 ， 头 像 和 作者 的 用 户 名 都 泻 染 成 链接 ， 指 向 用 户 的 资料 
页 面 。 所 用 的 CSS 样式 都 存储 在 应 用 的 static 目录 里 的 styles.css 文件 中 。 你 可 到 GitHub 
仓库 中 查看 这 个 文件 。 显 示 有 发 布 表单 和 博客 文章 列表 的 首页 如 图 11-1 所 示 。 


如 果 你 从 GitHub 上 克隆 了 这 个 应 用 的 Git 仓库 ， 那 么 可 以 执行 git checkout 
11a 检 出 应 用 的 这 个 版 本 。 这 个 版 本 包含 了 一 个 数据 库 迁 移 ， 签 出 代码 后 记 
得 要 执行 fLask db upgrade 命令 。 
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€ C 合 @Iocalhost:5000 


Hello, johnl! 


What's on your mind? 


Submit 


， nbarnes 2 days ago 
Bk lo voluptatibus perferendis quisquam molestias voluptas rem totam. Maxime optio repellendus quis 
sunt temporibus voluptate sunt. 


A salaslisa 2 days ago 
ey Dolore magnam adipisci laborum omnis quae beatae explicabo. Aperiam autem distinctio optio quae. 


hea3 cochrancaleb 2 days ago 
ES Explicabo eligendi minima impedit voluptas. Repellendus corporis error quisquam officiis eligendi 


quisquam. Dolorum consectetur praesentium alias magnam maiores. Sequi magni ut tenetur. 


Er samuel27 3 days ago 
oo Rem laboriosam numquam repudiandae ducimus distinctio. Assumenda quos molestias animi earum. 
Quaerat enim cumque odio perferendis quae suscipit. 

















图 11-1， 显示 有 博客 发 布 表单 和 博客 文章 列表 的 首页 
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11.2 在 资料 页 中 显示 博客 文章 


我 们 可 以 改进 一 下 用 户 资料 页 面 ， 在 上 面 显 示 该 用 户 发 布 的 博客 文章 列表 。 示 例 11-5 是 对 
视图 函数 所 做 的 改动 ， 用 以 获取 文章 列表 。 


示例 11-5 app/main/views.py: 获取 博客 文章 的 资料 页 面 路 由 
@main.route('/user/<username>') 
def user(username): 
user = User.query.filter_by(username=username).first() 
if user is None: 
abort(404) 
posts = user.posts.order_by(Post.timestamp.desc()).all() 
return render_template('user.html', user=user, posts=posts) 


用 户 发 布 的 博客 文章 列表 通过 User .posts 关系 获取 。User .posts 返回 的 结果 类 似 于 查询 对 
象 ， 因 此 可 像 常 规 查 询 对 象 那样 在 其 上 调用 过 滤器 ， 例 如 order_by()。 


与 index.html 模板 一 样 ，user.html 模板 也 要 使 用 一 个 HTML <ul> 元 素 演 染 博客 文章 列表 。 
但 是 维护 两 个 完全 相同 的 HTML 片段 副本 可 不 是 个 好 主意 。 遇 到 这 种 情况 ，Jinja2 提供 
的 inctude() 指令 就 非常 有 用 。 生 成 文章 列表 的 HIML 片段 可 以 移 到 一 个 单独 的 文件 
中 ， 然 后 在 index.html 和 user.html 中 将 其 导入 。 在 user.html 中 导入 该 文件 的 方式 如 示例 
11-6 所 示 。 


示例 11-6 ”app/templates/user.html: 显示 有 博客 文章 的 资料 页 面 模板 






































<h3>Posts by {{ user.username }}</h3> 
{% include '_posts.html' %} 


为 了 完成 这 种 新 的 模板 组 织 方式 ，index.html 模板 中 的 <ul> 元 素 需 要 移 到 新 模板 _posts. 
html 中 ， 并 像 上 面 那样 换 成 一 个 inctude 指令 。 注 意 ，_posts.html 模板 名 中 的 下 划 线 前 组 
不 是 必须 使 用 的 ， 这 只 是 一 种 习惯 用 法 ， 以 区 分 完整 模板 和 局 部 模板 。 




















如 果 你 从 GitHub 上 克隆 了 这 个 应 用 的 Git 仓库 ， 那 么 可 以 执行 git checkout 
11b 检 出 应 用 的 这 个 版 本 。 


11.3 分 页 显示 长 博客 文章 列表 


随 着 网 站 的 发 展 ， 博 客 文章 的 数量 会 不 断 增 多 。 如 果 在 首页 和 资料 页 显示 全 部 文章 ， 页 面 
加 载 速度 会 变 慢 ， 而 且 有 点 不 切实 际 。 在 Web 浏览 器 中 ， 内 容 多 的 网 页 需要 花费 更 多 的 时 
间 生 成 、 下 载 和 浑 染 ， 因 此 网 页 内 容 变 多 会 让 用 户 体验 变 差 。 这 一 问题 的 解决 方法 是 分 页 
显示 数据 并 分 段 泻 染 。 
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11.3.1 创建 虚拟 博客 文章 数据 
想 实现 博客 文章 分 页 ， 就 需要 一 个 包含 大 量 数据 的 测试 数据 库 。 手 动 添加 数据 库 记 录 费 时 
费力 ， 所 以 最 好 能 使 用 自动 化 方案 。 有 多 个 Python 包 可 用 于 生成 虚拟 信息 ， 其 中 功能 相对 
完善 的 是 Faker。 这 个 包 使 用 pip 安装 : 

(venv) $ pip install faker 


严格 来 说 ，Faker 包 并 不 是 这 个 应 用 的 依赖 ， 因 为 它 只 在 开发 过 程 中 使 用 。 为 了 区 分 生产 
环境 的 依赖 和 开发 环境 的 依赖 ， 我 们 可 以 用 requirements 子 目 录 替 换 requirements.txt 文件 ， 
在 该 目录 中 分 别 存储 不 同 环境 中 的 依赖 。 在 这 个 新 目录 中 ， 我 们 可 以 创建 一 个 dev.txt 文 
件 ， 列 出 开发 过 程 中 所 需 的 依赖 ， 再 创建 一 个 prod.txt 文件 ， 列 出 生产 环境 所 需 的 依赖 。 
由 于 两 个 环境 所 需 的 依赖 大 部 分 是 相同 的 ， 可 以 创建 一 个 common.txt 文件 ， 在 dev.txt 和 
prod.txt 中 使 用 -r 参数 将 其 导入 。dev.txt 文件 的 内 容 如 示例 11-7 所 示 。 


示例 11-7 requirements/dev.txt: 开发 需求 文件 


-FT Common.txt 
faker==0.7.18 


我 们 将 在 应 用 中 创建 一 个 新 模块 ， 在 里 面 定义 两 个 函数 ， 分 别 生 成 虚拟 的 用 户 和 文章 ， 如 
示例 11-8 所 示 。 


示例 11-8 app/fake.py: 生成 虚拟 用 户 和 博客 文章 


from random import randint 

from sqLaLchemy .exc import IntegrityError 
from faker import Faker 

from . import db 

from .models import User, Post 






































def users(count=100): 
fake = Faker() 
i=0 
while i < count: 

U = User(email=fake.email(), 
Username=fake.user_name()， 
password='password ' ， 
confirmed=True, 
name=fake.name(),， 
location=fake.city(), 
about_me=fake. text(), 
member_since=fake.past_date()) 

db.session.add(u) 

try: 

db.session.commit() 
i+= 1 

except IntegrityError: 

db.session.rollback() 


def posts(count=100): 
fake = Faker() 
User_count = User .query.count() 





for i in range(count ) : 
User .query.offset(randint(0, user_count - 1)).first() 
Post(body=fake. text(), 
timestamp=fake.past_date(), 
author=u) 
db.session.add(p) 
db.session.commit() 
这 些 虚 拟 对 象 的 属性 使 用 Faker 包 提 供 的 随机 信息 生成 器 生成 ， 可 以 生成 看 起 来 很 逼真 的 
姓名 、 电 子 邮 件 地 址 、 句 子 ， 等 等 。 
用 户 的 电子 邮件 地 址 和 用 户 名 必须 是 唯一 的 ， 但 Faker 是 随机 生成 这 些 信息 的 ， 因 
此 有 重复 的 风险 。 如 果 发 生 了 这 种 情况 (虽然 不 太 可 能 )， 提 交 数 据 库 会 话 时 会 抛 出 
IntegrityError 异常 。 此 时 ， 数 据 库 会 话 会 回 深 ， 取 消 添加 重复 用 户 的 尝试 。 函 数 中 的 循 
环 会 一 直 运 行 ， 直 到 生成 指定 数量 的 唯一 用 户 为 止 。 
随机 生成 文章 时 要 为 每 篇 文章 随机 指定 一 个 用 户 。 为 此 ， 我 们 使 用 offset() 查询 过 滤器 。 
这 个 过 滤器 会 跳 过 参数 指定 的 记录 数量 。 为 了 每 次 都 得 到 不 同 的 随机 用 户 ， 我 们 先 设 定 一 
个 随机 的 偏 移 ， 然 后 调用 first() 方法 。 
如 果 你 从 GitHub 上 克隆 了 这 个 应 用 的 Git 仓库 ， 那 么 可 以 执行 git checkout 
1tc 检 出 应 用 的 这 个 版 本 。 为 保证 安装 了 所 有 依赖 ， 还 要 执行 ptp install 


-rr _ requirements/dev.txt。 





























使 用 新 定义 的 这 两 个 函数 可 以 在 Python shell 中 轻松 生成 大 量 虚拟 用 户 和 文章 : 


(venv) $ flask shell 

>>> from app import fake 
>>> fake.users(100) 

>>> fake.posts(100) 


如 果 现 在 运行 应 用 ， 你 会 看 到 首页 显示 了 一 个 很 长 的 随机 博客 文章 列表 ， 而 且 由 大 量 不 同 
的 用 户 发 布 。 


11.3.2 ”在 页 面 中 泻 染 数据 
示例 11-9 展示 了 为 支持 分 页 而 对 首页 路 由 所 做 的 改动 。 


示例 11-9 app/main/views.py: 分 页 显示 博客 文章 列表 
@main.route('/', methods=['GET', 'POST']) 
def index(): 
# 
page = request.args.get('page', 1, type=int) 
pagination = Post.query.order_by(Post. timestamp.desc()).paginate( 
page, per_page=current_app.config['FLASKY_POSTS_PER_PAGE'], 
error_out=False) 
posts = pagination.items 
return render_template('index.html', form=form, posts=posts, 
pagination=pagination) 


渲染 的 页 数 从 请 求 的 查询 字符 串 (request.args) 中 获取 ， 如 果 没 有 明确 指定 ， 则 默认 演 
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染 第 1 页 。 参 数 type=int 确保 参数 在 无 法 转换 成 整数 时 返回 默认 值 。 


为 了 显示 某 页 中 的 记录 ， 查 询 对 象 最 后 不 能 调用 alLL() 方法 了 ， 现 在 要 调用 Flask-SQLAlchemy 
提供 的 paginate() 方法 。paginate() 方法 的 第 一 个 参数 一 一 也 是 唯一 必需 的 参数 一 一 是 
页 数 。 可 选 参数 per_page 指定 每 页 显示 的 记录 数量 ， 如 果 没 有 指定 ， 则 默认 显示 20 个 记 
录 。 另 一 个 可 选 参数 为 error_out， 如 果 设 为 True (默认 值 )， 则 请 求 页 数 超出 范围 时 返回 
404 错误 ， 如 果 设 为 False， 则 页 数 超出 范围 时 返回 一 个 空 列表 。 为 了 能 够 很 便利 地 配置 每 
页 显示 的 记录 数量 ， 参 数 per_page 的 值 从 应 用 的 配置 变量 FLASKY_POSTS_PER_PAGE 中 读 取 。 
这 个 配置 在 config.py 中 设置 。 


这 样 修改 之 后 ， 首 页 中 的 文章 列表 会 只 显示 有 限 数量 的 文章 。 若 想 查 看 第 2 页 中 的 文章 ， 
则 要 在 浏览 器 地 址 栏 中 的 URL 后 加 上 查询 字符 串 ?page=2。 


11.3.3 添加 分 页 导航 


paginate() 方法 的 返回 值 是 一 个 Pagination 类 对 象 ， 这 个 类 在 Flask-SQLAlchemy 中 定义 。 
这 个 对 象 包含 很 多 属性 ， 用 于 在 模板 中 生成 分 页 链接 ， 因 此 将 其 作为 参数 传人 了 模板 。 分 
页 对 象 的 属性 简介 如 表 11-1 所 示 。 


表 11-1: Flask-SQLAIchemy 分 页 对 象 的 属性 














































































































属 性 说 明 

items 当前 页 面 中 的 记录 

query 分 页 的 源 查 询 

page 当前 页 数 

prev_num 上 一 页 的 页 数 

next_num 下 一 页 的 页 数 

has_next 如 果 有 下 一 页 ， 值 为 True 
has_prev 如 果 有 上 一 页 ， 值 为 True 
pages 查询 得 到 的 总 页 数 
per_page 每 页 显示 的 记录 数量 
total 查询 返回 的 记录 总 数 





分 页 对 象 还 有 一 些 方法 ， 如 表 11-2 所 示 。 
表 11-2: Flask-SQLAIchemy 分 页 对 象 的 方法 















































放流 说 明 

iter_pages(left_edge=2， 一 个 从 代 器 ， 返 回 一 个 在 分 页 导航 中 显示 的 页 数列 表 。 这 个 列表 的 最 左边 

left_current=2, 显示 left_edge 页 ， 当 前 页 的 左边 显示 left_current 页 ， 当 前 页 的 右边 显 

right_current=5, 示 right_current 页 ， 最 右边 显示 right_edge 页 。 例 如 ， 在 一 个 100 页 的 列 

Sight:edgess) 表 中 ， 当 前 页 为 第 50 页 ， 使 用 默认 配置 ， 这 个 方法 会 返回 以 下 页 数 : 1、2、 
None、48、49、50、51、52、53、54、55、None、99、100。None 表示 页 数 之 
间 的 间隔 

prev() 上 一 页 的 分 页 对 象 

next() 下 一 页 的 分 页 对 象 




















拥有 这 么 强大 的 对 象 和 Bootstrap 中 的 分 页 CSS 类 ， 我 们 就 能 很 容易 地 在 模板 底部 构建 一 
个 分 页 导航 。 示 例 11-10 是 以 Jinja2 宏 的 形式 实现 的 分 页 导航 。 


示例 11-10 ”app/templates/_macros.html: 分 页 模板 宏 


{% macro pagination widget(pagination, endpoint) %} 
<ul class="pagination"> 
<Li{% if not pagination.has_prev %} class="disabled"{% endif %}> 
<a href="{% if pagination.has_prev %}{{ url_for(endpoint, 
page = pagination.page - 1, **kwargs) }}{% else %}#{% endif %}"> 
&Laquo; 
</a> 
</li> 
{% for p in pagination.iter_pages() %} 
{% if p %} 
{% if p == pagination.page %} 
<li class="active"> 
<a href="{{ url_for(endpoint, page = p, **kwargs) }}">{{ p }}</a> 
</li> 
{% else %} 
<li> 
<a href="{{ url_for(endpoint, page = p, **kwargs) }}">{{ p }}</a> 
</li> 
{% endif %} 
{% else %} 
<li class="disabled"><a href="#">&hellip;</a></li> 
{% endif %} 
{% endfor %} 
<Li{% if not pagination.has_next %} class="disabled"{% endif %}> 
<a href="{% if pagination.has_next %}{{ url_for(endpoint, 
page = pagination.page + 1, **kwargs) }}{% else %}#{% endif %}"> 
&raquo; 
</a> 
</li> 
</ul> 
{% endmacro %} 


这 个 宏 创建 了 一 个 Bootstrap 分 页 元 素 ， 即 一 个 有 特殊 样式 的 无 序列 表 ， 其 中 定义 了 下 述 页 

押 链 接 。 

。“ 上 一 页 ”链接 。 如 果 当 前 页 是 第 一 页 ， 为 这 个 链接 加 上 CSS disabled 类 。 

。 分 页 对 象 的 iter_pages() 迭 代 器 返回 的 所 有 页 面 链 接 。 这 些 页 面 被 演 染 成 具有 明确 页 
数 的 链接 ， 页 数 在 urL_for() 的 参数 中 指定 。 当 前 显示 的 页 面 使 用 CSS active 类 高 亮 
显示 。 页 数列 表 中 的 间隔 使 用 省 略 号 表示 。 

。“ 下 一 页 ”链接 。 如 果 当 前 页 是 最 后 一 页 ， 则 会 禁用 这 个 链接 。 

Jinja2 宏 的 参数 列表 中 不 用 加 入 **kwargs 即 可 接收 关键 字 参 数 。 分 页 宏 把 接收 到 的 所 有 关 

键 字 参数 都 传 给 生成 分 页 链接 的 urL_for() 方法 。 这 种 方式 也 可 在 路 由 中 使 用 ， 例 如 包含 

动态 部 分 的 资料 页 再 


pagination_widget 宏 可 放 在 index.html 和 user.html 中 引入 的 _posts.html 模板 后 面 。 示 例 
11-11 是 在 应 用 首页 使 用 这 个 宏 的 方法 。 
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示例 11-11 ”app/templates/index.html: 在 博客 文章 列表 下 面 添加 分 页 导航 


{% extends "base.html" %} 
{% import "bootstrap/wtf.html" as wtf %} 
{% import "_macros.html" as macros %} 


{% include '_posts.html' %} 
<div class="pagination"> 
{{ macros.pagination widget(pagination, '.index') }} 
</div> 
{% endif %} 


页 面 中 的 分 页 链接 如 图 11-2 所 示 。 

















©09 岂 Fasky 





一 C 合 @Iocalhost:5000/?p: 


robert40 9 days ago 
Cupiditate dolorem voluptatem expedita porro. Cupiditate nihil in aspernatur expedita beatae harum. Vel 
itaque rem tenetur eius. Labore necessitatibus consequuntur repudiandae repudiandae. 


elee 9 days ago 
Blanditiis aliquid quam sunt dolores. Sint iste reprehenderit totam necessitatibus qui. 


1 2 “0 学 8 四 10 11 12 13 5 30 31 














11-2: 博客 文章 分 页 导航 


如 果 你 从 GitHub 上 克隆 了 这 个 应 用 的 Git 仓库 ， 那 么 可 以 执行 git checkout 
11d 检 出 应 用 的 这 个 版 本 。 








11.4 使 用 Markdown 和 Flask-PageDown 支 持 富 
文本 文章 


对 于 发 布 短 消息 和 状态 更 新 来 说 ， 纯 文本 足够 用 了 ， 但 如 果 用 户 想 发 布 长 文章 ， 就 会 觉 
得 在 格式 上 受到 了 限制 。 本 节 要 将 输入 文章 的 多 行文 本 输入 框 升级 ， 让 其 支持 Markdown 
(https://daringfireball.net/projects/markdown/) 句法 ， 还 要 添加 富 文 本 文章 的 预览 功能 。 

实现 这 个 功能 要 用 到 一 些 新 包 。 

。 PageDown: 使 用 JavaScript 实现 的 客户 端 Markdown 到 HTML 转换 程序 。 

。 Flask-PageDown: 为 Flask 包装 的 PageDown， 把 PageDown 集成 到 Flask-WTF 表单 中 。 
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。 Markdown: 使 用 Python 实现 的 服务 器 端 Markdown 到 HTML 转换 程序 。 
。 Bleach: 使 用 Python 实现 的 HTML 清理 程序 。 


这 些 Python 包 可 使 用 pip 安装 : 


(venv) $ pip install flask-pagedown markdown bleach 




















11.4.1 使 用 Flask-PageDown 


Flask-PageDown 扩展 定义 了 一 个 PageDownField 类 ， 这 个 类 和 WTForms 中 的 TextAreaField 
接口 一 致 。 使 用 PageDownField 字段 之 前 ， 先 要 初始 化 扩展 ， 如 示例 11-12 所 示 。 


示例 11-12 app/_init .py: 初始 化 Flask-PageDown 


from fLask_pagedown import PageDown 
i 

pagedown = PageDown() 

$s 

def create_app(config_name): 


pagedown.init_app(app) 
# 


若 想 把 首页 中 的 多 行文 本 控件 转换 成 Markdown 富 文本 编辑 器 ，PostForm 表单 中 的 body 字 
段 必 须 改 成 PageDownField 字段 ， 如 示例 11-13 所 示 。 





示例 11-13 ”app/main/forms.py: 支持 Markdown 的 文章 表单 
from flask_pagedown.fields import PageDownField 


class PostForm(FlaskForm): 
body = PageDownField("What's on your mind?", validators=[Required()]) 
submit = SubmitField('Submit') 


Markdown 预览 使 用 PageDown 库 生 成 ， 因 此 要 把 相关 的 文件 添加 到 模板 中 。Flask-Page 
Down 简化 了 这 个 过 程 ， 提 供 了 一 个 模板 宏 ， 从 CDN 中 加 载 所 需 的 文件 ， 如 示例 11-14 所 示 。 


示例 11-14 app/templates/index.html: Flask-PageDown 模板 声明 


{% block scripts %} 

{{ super() }} 

{{ pagedown.include pagedown() }} 
{% endblock %} 

















如 果 你 从 GitHub 上 克隆 了 这 个 应 用 的 Git 仓库 ， 那 么 可 以 执行 git checkout 
11le 检 出 应 用 的 这 个 版 本 。 为 保证 安装 了 所 有 依赖 ， 请 执行 pip install -r 


requirements/dev.txt, 





做 了 上 述 修 改 后， 在 多 行文 本 字段 中 输入 的 Markdown 格式 文本 会 被 立即 泻 染 成 HTML， 
显示 在 输入 框 下 方 。 富 文本 博客 文章 表单 如 图 11-3 所 示 。 




















@@ 亲 Fasy 


一 CG 合 @Iiocalhost:5000 


Hello, john! 





What's on your mind? 


# This is atop-level heading 
This is a “*regular”* paragraph 


This is a top-level heading 


This is a regular paragraph 
Submit 


wespinoza 2 days ago 
入 玉 Maiores illo non doloremque ratione delectus. Facilis officiis corporis nihil perferendis occaecati 


odio et explicabo. 











图 11-3; 富 文本 博客 文章 表单 


11.4.2 ”在 服务 器 端 处 理 富 文本 


提交 表单 后 ，POST 请 求 只 会 发 送 纯 Markdown 文本 ， 页 面 中 显示 的 HTML 预览 会 被 丢掉 。 
随 表单 一 起 发 送 生 成 的 HTML 预览 有 安全 隐患 ， 因 为 攻击 者 能 很 轻松 地 修改 HTML 代码 ， 
使 其 和 Markdown 源 不 匹配 ， 然 后 再 提交 表单 。 为 了 安全 起 见 ， 应 该 只 提交 Markdown 源 
文本 ， 然 后 在 服务 器 上 使 用 Markdown (使 用 Python 编写 的 Markdown 到 HTML 转换 程 
序 ) 将 其 转换 成 HTM L。 得 到 HTML 后， 再 使 用 Bleach 进行 清理 ， 确 保 其 中 只 包含 几 个 
允许 使 用 的 HTML 标签 。 


把 Markdown 格式 的 博客 文章 转换 成 HTML 的 过 程 可 以 在 _posts.html 模板 中 完成 ， 但 这 么 
做 效率 不 高 ， 因 为 每 次 泻 染 页 面 都 要 转换 一 次 。 为 了 避免 重复 工作 ， 我 们 可 在 创建 博客 文 
章 时 做 一 次 性 转换 ， 把 结果 缓存 在 数据 库 中 。 转 换 后 的 博客 文章 HTML 代码 缓存 在 Post 
模型 的 一 个 新 字段 中 ， 在 模板 中 可 以 直接 调用 。 文 章 的 Markdown 源 文本 还 要 保存 在 数据 
库 中 ， 万 一 需要 编辑 时 使 用 。 示 例 11-15 是 对 Post 模型 所 做 的 改动 。 


示例 11-15 app/models.py: 在 Post 模型 中 处 理 Markdown 文本 


from markdown import markdown 
import bleach 


























class Post(db.Model): 


入 

body_html = db.CoLumn(db.Text) 
Hi 

@staticmethod 


def on_changed_body(target, value, oldvalue, initiator): 
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allowed tags = ['a', 'abbr', 'acronym', 'b', 'blockquote', 'code', 
‘em', 'i', 'li', 'ol', 'pre', 'strong', 'ul', 
"hi 'h2', 37 'p'] 
target.body_html = bleach.linkify(bleach.clean( 
markdown(value, output_ format='html'), 
tags=allowed_tags, strip=True)) 


db.event.listen(Post.body, 'set', Post.on_changed_body) 


on_changed_body() 函数 注册 在 body 字段 上 ， 是 SQLAlchemy “set” 事 件 的 监听 程序 ， 这 
意味 着 只 要 body 字段 设 了 新 值 ， 这 个 函数 就 会 自动 被 调用 。on_changed_body() 函数 把 
body 字段 中 的 文本 泻 染 成 HTML 格式 ， 将 结果 保存 在 body_html 中 ， 自 动 且 高 效 地 完成 
Markdown 文本 到 HTML 的 转换 。 

真正 的 转换 过 程 分 3 步 完 成 。 首 先 ，markdown() 函数 初步 把 Markdown 文本 转换 成 HTML。 
然后 ， 把 得 到 的 结果 和 人 允许 使 用 的 HTML 标签 列表 传 给 clean() 函数 。clean() 函数 删除 
所 有 不 在 白 名 单 中 的 标签 。 转 换 的 最 后 一 步 由 Linkify() 函数 完成 ， 这 个 函数 由 Bleach 提 
供 ， 把 纯 文 本 中 的 URL 转换 成 合适 的 <a> 链接 。 最 后 一 步 是 很 有 必要 的 ， 因 为 Markdown 
规范 没有 为 自动 生成 链接 提供 官方 支持 ， 但 这 是 个 十 分 便利 的 功能 。 在 客户 端 ，PageDown 
以 扩展 的 形式 实现 了 这 个 功能 ， 因 此 在 服务 器 上 要 调用 Linkify() 函数 ， 确 保 结 果 一 致 。 
最 后 ， 如 果 post.body_html 字段 存在 ， 还 要 把 模板 中 的 post.body 换 成 post.body_htnml， 
如 示例 11-16 所 示 。 


示例 11-16 ”app/templates/_posts.html: 在 模板 中 使 用 文章 内 容 的 HTML 格式 


























<div class="post-body"> 
{% if post.body_html %} 
{{ post.body_html | safe }} 
{% else %} 


{{ post.body }} 
{% endif %} 
</div> 


泻 染 HTML 格式 内 容 时 使 用 | safe 后 级 ， 其 目的 是 告诉 Jinja2 不 要 转 义 HTML 元 素 。 出 
于 安全 考虑 ， 默 认 情 况 下 Jinja2 会 转 义 所 有 模板 变量 ， 但 是 从 Markdown 到 HTML 的 转换 
是 在 我 们 自己 的 服务 器 上 完成 的 ， 因 此 可 以 放心 直接 泻 染 。 

如 果 你 从 GitHub 上 克隆 了 这 个 应 用 的 Git 仓库 ， 那 么 可 以 执行 git checkout 

11f 检 出 应 用 的 这 个 版 本 。 该 版 本 包含 一 个 数据 库 迁 移 ， 签 出 代码 后 记得 

要 运行 flask db upgrade 目录 。 为 保证 安装 了 所 有 依赖 ， 还 要 执行 pip 


install -r requirements/dev.txt, 




















11.5 博客 文章 的 固定 链接 


用 户 有 时 希望 能 在 社交 网 络 中 和 朋友 分 享 茶 篇 博客 文章 的 链接 。 为 此 ， 每 篇 文章 都 要 有 一 
个 专 页 ， 使 用 唯一 的 URL 引用 。 支 持 固 定 链接 功能 的 路 由 和 视图 函数 如 示例 11-17 所 示 。 
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示例 11-17 app/main/views.py: 为 文章 提供 固定 链接 
@main.route('/post/<int:id>') 
def post(id): 
post = Post.query.get or_404(id) 
return render_template('post.html', posts=[post]) 


博客 文章 的 URL 使 用 插入 数据 库 时 分 配 的 唯一 id 字段 构建 。 


对 某 些 类 型 的 应 用 来 说 ， 更 适合 使 用 可 读 性 高 的 字符 串 而 不 是 数字 ID 构建 
固定 链接 。 除 了 数字 了 DP 之 外 ， 应 用 还 可 以 为 博客 文章 起 个 别名 ， 即 根据 文 
章 的 标题 或 前 几 个 词 生成 的 唯一 字符 串 。 


























注意 ，posthtml 模板 接收 一 个 列表 作为 参数 ， 这 个 列表 只 有 一 个 元 素 ， 即 要 泻 染 的 文章 。 
传 入 列表 是 为 了 方便 ， 因 为 这 样 ，index.html 和 user.html 引用 的 _posts.html 模板 就 能 在 这 
个 页 面 中 使 用 。 


固定 链接 添加 到 通用 模板 _posts.html 中 ， 显 示 在 文章 下 方 ， 如 示例 11-18 所 示 。 
示例 11-18 ”app/templates/_posts.html: 加 上 文章 的 固定 链接 


<ul class="posts"> 
{% for post in posts %} 
<li class="post"> 





<div class="post-content"> 


<div class="post-footer"> 
<a href="{{ url_for('.post', id=post.id) }}"> 
<span class="label label-default">Permalink</span> 
</a> 
</div> 
</div> 
</li> 
{% endfor %} 
</ul> 


这 染 固定 链接 页 面 的 post.html 模板 如 示例 11-19 所 示 ， 其 中 引入 了 上 述 模板 。 


示例 11-19 ”app/templates/post.html: 固定 链接 模板 
{% extends "base.html" %} 





{% block title %}Flasky - Post{% endblock %} 


{% block page_content %} 
{% include '_posts.html' %} 
{% endblock %} 


如 果 你 从 GitHub 上 克隆 了 这 个 应 用 的 Git 仓库 ， 那 么 可 以 执行 git checkout 
11g 检 出 应 用 的 这 个 版 本 。 














11.6 博客 文章 编辑 器 


与 博客 文章 相关 的 最 后 一 个 功能 是 文章 编辑 器 ， 让 用 户 编辑 自己 的 文章 。 博 客 文章 编辑 器 
显示 在 单独 的 页 面 中 ， 而 且 也 基于 Flask-PageDown 实现 ， 因 此 页 面 中 要 有 个 文本 框 ， 显 示 
博客 文章 的 Markdown 文本 ， 并 在 下 方 显示 预览 。edit_post.html 模板 如 示例 11-20 所 示 。 


























示例 11-20 ”app/templates/edit_post.html: 编辑 博客 文章 的 模板 


{% extends "base.html" %} 
{% import "bootstrap/wtf.html" as wtf %} 


{% block title %}Flasky - Edit Post{% endblock %} 


{% block page_content %} 

<div class="page-header"> 
<h1>Edit Post</h1> 

</div> 

<div> 
{{ wtf.quick_form(form) }} 

</div> 

{% endblock %} 


{% block scripts %} 


{{ super() }} 
{{ pagedown.include pagedown() }} 
{% endblock %} 


博客 文章 编辑 器 使 用 的 路 由 如 示例 11-21 所 示 。 


示例 11-21 app/main/views.py: 编辑 博客 文章 的 路 由 
@main.route('/edit/<int:id>', methods=['GET', 'POST']) 
@login_required 
def edit(id): 

post = Post.query.get or_404(id) 





if current_user != post.author and \ 
not current_user.can(Permission.ADMIN): 
abort(403) 


form = PostForm() 
if form.validate on_submit(): 
post.body = form.body.data 
db.session.add(post) 
db.session.commit() 
flash('The post has been updated.') 
return redirect(url_for('.post', id=post.id)) 
form.body.data = post.body 
return render_template('edit post.html', form=form) 


这 个 视图 函数 只 允许 博客 文章 的 作者 编辑 文章 ， 但 管理 员 例 外 ， 管 理 





























员 能 编辑 所 有 用 户 





的 文章 。 如 果 用 户 试 图 编辑 其 他 用 户 的 文章 ， 则 视图 函数 返回 403 错误 。 这 里 使 用 的 








PostForm 表单 类 和 首页 中 使 用 的 是 同一 个 。 
为 了 让 功能 完整 ， 我 们 还 可 以 在 每 篇 博客 文章 的 下 
页 面 的 链接 ， 如 示例 11-22 所 示 。 




















= 
HH 




















定 链接 的 旁边 添加 一 个 指向 编辑 
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示例 11-22 ”app/templates/_posts.html: 编辑 博客 文章 的 链接 


<ul class="posts"> 
{% for post in posts %} 
<li class="post"> 


<div class="post-content"> 
<div class="post-footer"> 


{% if current_user == post.author %} 
<a href="{{ url_for('.edit', id=post.id) }}"> 
<span class="label label-primary">Edit</span> 
</a> 
{% elif current_user.is_ administrator() %} 
<a href="{{ url_for('.edit', id=post.id) }}"> 
<span class="label label-danger">Edit [Admin]</span> 
</a> 
{% endif %} 
</div> 
</div> 
</li> 
{% endfor %} 
</ul> 


这 次 修改 在 当前 用 户 发 布 的 博客 文章 下 面 添 加 一 个 Edit 链接 。 如 果 当 前 用 户 是 管理 员 ， 那 
么 所 有 文章 下 面 都 会 有 编辑 链接 。 为 管理 员 显 示 的 链接 样式 有 点 不 同 ， 以 从 视觉 上 表明 这 
是 管理 功能 。 图 11-4 是 在 浏览 器 中 显示 的 编辑 链接 和 固定 链接 。 























09 Fasy 





和 GO © localhost:5000 
john 4 minutes ago 


This is a top-level heading 
This is a regular paragraph 


ED | Pormaink | 


六 换 wespinoza 2 days ago 
入 对 Maiores illo non doloremque ratione delectus. Facilis officiis corporis nihil perferendis occaecati 














图 11-4: 博客 文章 的 编辑 链接 和 固定 链接 





如 果 你 从 GitHub 上 克隆 了 这 个 应 用 的 Git 仓库 ， 那 么 可 以 执行 git checkout 
11h 检 出 应 用 的 这 个 版 本 。 
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第 12 章 


关注 者 








社交 Web 应 用 允许 用 户 之 间 相互 联系 。 不 同 的 应 用 以 不 同 的 名 称 称呼 这 样 的 关系 ， 例 如 关 
注 者 、 好 友 、 联 系 人 、 联 络 人 或 伙伴 。 不 管 使 用 什么 名 称 ， 其 功能 都 是 一 样 的 ， 都 要 记录 
两 个 用 户 之 间 的 定向 联系 ， 在 数据 库 查询 中 也 要 使 用 这 种 联系 。 


在 本 章 ， 你 将 学 到 如 何在 Flasky 中 实现 关注 功能 ， 让 用 户 “ 关 注 ” 其 他 用 户 ， 并 在 首页 只 
显示 所 关注 用 户 发 布 的 博客 文章 列表 。 


12.1 再 论 数 据 库 关系 


我 们 在 第 5 章 介绍 过 ， 数 据 库 使 用 关系 建立 记录 之 间 的 联系 。 其 中 ， 一 对 多 关系 是 最 常用 
的 关系 类 型 ， 它 把 一 个 记录 和 一 组 相关 的 记录 联系 在 一 起 。 实 现 这 种 关系 时 ， 要 在 “多 ” 
这 一 侧 加 入 一 个 外 键 ， 指 向 “一 ”这 一 侧 连 接 的 记录 。 本 书 开发 的 示例 应 用 现在 包含 两 个 
对 多 关系 : 一 个 把 用 户 角色 和 一 组 用 户 联系 起 来 ， 另 一 个 把 用 户 和 发 布 的 博客 文章 联系 
起 来 。 

多 数 其 他 关系 类 型 都 可 以 从 一 对 多 类 型 中 衍生 。 多 对 一 关系 从 “多 ”这 一 侧 看 ， 就 是 一 对 
多 关系 。 一 对 一 关系 是 简化 版 的 一 对 多 关系 ， 限 制 “ 多 ”这 一 侧 最 多 只 能 有 一 个 记录 。 唯 
一 不 能 从 一 对 多 关系 中 简单 演化 出 来 的 类 型 是 多 对 多 关系 ， 这 种 关系 的 两 侧 都 有 多 个 记 
录 。 下 一 市 将 详细 讨论 多 对 多 关系 。 


12.1.1 多 对 多 关系 


一 对 多 关系 、 多 对 一 关系 和 一 对 一 关系 至 少 都 有 一 侧 是 单个 实体 ， 所 以 记录 之 间 的 联系 通 
过 外 键 实 现 ， 让 外 键 指向 那个 实体 。 但 是 ， 两 侧 都 是 “多 ”的 关系 应 该 如 何 实现 呢 ? 
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下 面 以 一 个 典型 的 多 对 多 关系 为 例 ， 即 一 个 记录 学 生 和 他 们 所 选课 程 的 数据 库 。 很 显然 ， 
你 不 能 在 学 生 表 中 加 入 一 个 指向 课程 的 外 键 ， 因 为 一 个 学 生 可 以 选择 多 门 课 程 ， 一 个 外 键 
不 够 用 。 同 样 ， 你 也 不 能 在 课程 表 中 加 入 一 个 指向 学 生 的 外 键 ， 因 为 一 个 课程 有 多 个 学 生 
选择 。 两 侧 都 需要 一 组 外 键 。 
这 种 问题 的 解决 方法 是 添加 第 三 张 表 ， 这 个 表 称 为 关联 表 。 现 在 ， 多 对 多 关系 可 以 分 解 成 
原 表 和 关联 表 之 间 的 两 个 一 对 多 关系 。 图 12-1 描绘 了 学 生 和 课程 之 间 的 多 对 多 关系 。 


Students registrations classes 















































student_id 
class_id SS 














12-1: 多 对 多 关系 示例 
这 个 例子 中 的 关联 表 是 registrations， 表 中 的 每 一 行 表示 一 个 学 生 注册 的 一 门 课程 。 


查询 多 对 多 关系 分 成 两 步 。 若 想 知 道 某 位 学 生 选 择 了 哪些 课程 ， 要 先 从 学 生 和 广 册 之 间 的 
一 对 多 关系 开始 ， 获 取 这 位 学 生 在 registrations 表 中 的 所 有 记录 ， 然 后 再 按照 多 到 一 的 
方向 遍历 课程 和 注册 之 间 的 一 对 多 关系 ， 找 到 这 位 学 生 在 registrations 表 中 各 记录 所 对 
应 的 课程 。 同 样 ， 若 想 找到 选择 了 某 门 课程 的 所 有 学 生 ， 要 先 从 课程 表 中 开始 ， 获 取 其 在 
registrations 表 中 的 记录 ， 再 获取 这 些 记 录 连 接 的 学 生 。 


通过 遍历 两 个 关系 来 获取 查询 结果 的 做 法 听 起 来 有 难度 ， 不 过 像 前 例 这 种 简单 关系 ， 
SQLAIlchemy 就 可 以 完成 大 部 分 操作 。 图 12-1 中 的 多 对 多 关系 可 使 用 下 述 代码 表示 : 


registrations = db.Table('registrations', 
db.CoLumn('student_id' db.Integer, db.ForeignKey('students.id')), 
db.Column('class_id', db.Integer, db.ForeignKey('classes.id')) 

) 


class Student(db.Model): 
id = db.Column(db.Integer, primary_key=True) 
name = db.Column(db.String) 
classes = db.relationship('Class', 
secondary=registrations, 
backref=db.backref('students', lazy='dynamic'), 
lazy='dynamic') 






























































class Class(db.Model): 
id = db.Column(db.Integer, primary_key=True) 
name = db.Column(db.String) 


多 对 多 关系 仍 使 用 定义 一 对 多 关系 的 db.relationship() 方法 定义 ， 但 在 多 对 多 关系 中 ， 必 
须 把 secondary 参数 设 为 关联 表 。 多 对 多 关系 可 以 在 任何 一 个 类 中 定义 ，backref 参数 会 处 理 
好 关系 的 另 一 人 出。 关联 表 就 是 一 个 简单 的 表 ， 不 是 模型 ，SQLAlchemy 会 自动 接管 这 个 表 。 
classes 关系 使 用 列表 语义 ， 这 样 处 理 多 对 多 关系 特别 简单 。 假 设 学 生 是 s， 课 程 是 c， 学 
生 注 册 课 程 的 代码 为 : 
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>>> s.classes.append(c) 
>>> db.session.add(s) 


列 出 学 生 s 注册 的 课程 以 及 注册 了 课程 c 的 学 生 也 很 简单 


>>> s.classes.all() 
>>> c.students.all() 


Class 模型 中 的 students 关系 由 参数 db.backref() 定义 。 注 意 ， 这 个 关系 中 还 指定 了 
lazy='dynamic' 参数 ， 所 以 关系 两 侧 返 回 的 查询 都 可 接受 额外 的 过 滤器 。 
如 果 后 来 学 生 s 决定 不 选课 程 c 了 ， 那 么 可 使 用 下 面 的 代码 更 新 数据 库 : 


>>> s.classes.remove(c) 


12.1.2” 自 引用 关系 

多 对 多 关系 可 用 于 实现 用 户 之 间 的 关注 ， 但 存在 一 个 问题 。 在 学 生 和 课程 的 例子 中 ， 关 联 
表 链接 的 是 两 个 不 同 的 实体 。 但 是 ， 表 示 用 户 关注 其 他 用 户 时 ， 只 有 用 户 一 个 实体 ， 没 有 
第 二 个 实体 。 

如 果 关系 中 的 两 侧 都 在 同一 个 表 中 ， 这 种 关系 称 为 自 引用 关系 。 在 关注 中 ， 关 系 的 左 便 是 
用 户 实体 ， 可 以 称 为 “关注 者 ”， 关 系 的 右 侧 也 是 用 户 实体 ， 但 这 些 是 “被 关注 者 "。 从 概 
念 上 来 看 ， 自 引用 关系 和 普通 关系 没什么 区 别 ， 只 是 不 易 理解 。 图 12-2 是 自 引用 关系 的 数 
据 库 图 解 ， 表 示 用 户 之 间 的 关注 。 
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12-2: 关注 者 ， 多 对 多 关系 


本 例 的 关联 表 是 foLtows， 其 中 每 一 行 表示 一 个 用 户 关注 了 另 一 个 用 户 。 图 中 左边 表示 的 
对 多 关系 把 用 户 和 follows 表 中 的 一 组 记录 联系 起 来 ， 用 户 是 关注 者 。 图 中 右边 表示 的 
一 对 多 关系 把 用 户 和 follows 表 中 的 一 组 记录 联系 起 来 ， 用 户 是 被 关注 者 。 


12.1.3 ”高 级 多 对 多 关系 


使 用 前 一 节 介 绍 的 自 引 用 多 对 多 关系 可 在 数据 库 中 表示 用 户 之 间 的 关注 ， 但 却 有 个 限制 。 
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使 用 多 对 多 关系 时 ， 往 往 需要 存储 所 连 两 个 实体 之 间 的 额外 信息 。 对 用 户 之 间 的 关注 来 
说 ， 可 以 存储 用 户 关 注 另 一 个 用 户 的 日 期 ,这样 就 能 按照 时 间 顺 序列 出 所 有 关注 者 。 这 种 
信息 只 能 存储 在 关联 表 中 ， 但 是 在 之 前 实现 的 学 生 和 课程 之 间 的 关系 中 ， 关 联 表 是 完全 由 
SQLAIlchemy 掌控 的 内 部 表 ， 我 们 无 法 插手 。 


为 了 能 在 关系 中 处 理 自 定义 的 数据 ， 我 们 必须 提升 关联 表 的 地 位 ， 使 其 变 成 应 用 可 访问 的 
模型 。 新 的 关联 表 如 示例 12-1 所 示 ， 使 用 Fotlow 模型 表示 。 


示例 12-1 app/models.py: 关注 关系 中 关联 表 的 模型 实现 
class Follow(db.Model): 

__tablename _ = 'follows' 

follower_id = db.Column(db.Integer, db.ForeignKey('users.id'), 
primary_key=True) 

foLLowed id = db.Column(db.Integer, db.ForeignKey('users.id'), 
primary_key=True) 

timestamp = db.Column(db.DateTime, default=datetime.utcnow) 


SQLAIchemy 不 能 直接 使 用 这 个 关联 表 ， 因 为 如 果 这 么 做 应 用 就 无 法 访问 其 中 的 自 定义 字 
段 。 相 反 地 ， 要 把 这 个 多 对 多 关系 的 左右 两 侧 拆 分 成 两 个 基本 的 一 对 多 关系 ， 而 且 要 定义 
成 标准 的 关系 。 相 关 代 码 如 示例 12-2 所 示 。 


示例 12-2 app/models.py: 使 用 两 个 一 对 多 关系 实现 的 多 对 多 关系 
class User(UserMixin, db.Model): 
,es 
followed = db.relationship('Follow', 
foreign_keys=[Follow.follower_id], 
backref=db.backref('follower', lazy='joined'), 
Lazy= 'dynamic ' ， 
cascade='all, delete-orphan') 
followers = db.relationship('Follow', 
foreign_keys=[Follow.followed_id], 
backref=db.backref('followed', lazy='joined'), 
lazy='dynamic', 
cascade='all, delete-orphan') 


在 这 段 代 码 中 ，followed 和 followers 关系 都 定义 为 单独 的 一 对 多 关系 。 注 意 ， 为 了 消除 外 


键 间 的 歧义 ， 定 义 关 系 时 必须 使 用 可 选 参数 foreign_keys 指定 外 键 。 而 且 ，db.backref() 参 
数 并 不 是 指定 这 两 个 关系 之 间 的 引用 关系 ， 而 是 回 引 FoLLow 模型 。 


回 引 中 的 Lazy 参数 指定 为 joined。 这 种 lazy 模式 可 以 实现 立即 从 联结 查询 中 加 载 相 关 对 
象 。 例 如 ， 如 果 某 个 用 户 关注 了 100 个 用 户 ， 调 用 user.followed.all() 后 会 返回 一 个 列 
表 ， 其 中 包含 100 个 Follow 实例 ， 每 一 个 实例 的 follower 和 followed 回 引 属性 都 指向 相 
应 的 用 户 。 设 定 为 Lazy=' joined' 模式 ， 就 可 在 一 次 数据 库 查 询 中 完成 这 些 操 作 。 如 果 把 
lazy 设 为 默认 值 select， 那 么 首次 访问 follower 和 foLLowed 属性 时 才 会 加 载 对 应 的 用 户 ， 
而 且 每 个 属性 都 需要 一 个 单独 的 查询 ， 这 就 意味 着 获取 全 部 被 关注 用 户 时 需要 增加 100 次 
额外 的 数据 库 查 询 。 

这 两 个 关系 中 ，User 一 侧 设 定 的 Lazy 参数 作用 不 一 样 。lazy 参数 都 在 “一 ”这 一 侧 设 定 ， 
返回 的 结果 是 “多 ”这 一 侧 中 的 记录 。 上 述 代码 使 用 的 是 dynamic， 因 此 关系 属性 不 会 直 
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接 返 回 记 录 ， 而 是 返回 查询 对 象 ， 所 以 在 执行 查询 之 前 还 可 以 添加 额外 的 过 滤器 。 


cascade 参数 配置 在 父 对 象 上 执行 的 操作 对 相关 对 象 的 影响 。 比 如 ， 层 县 选项 可 设 定 为 : 
将 用 户 添 加 到 数据 库 会 话 后 ， 要 自动 把 所 有 关系 的 对 象 都 添加 到 会 话 中 。 层 又 选项 的 默认 
值 能 满足 多 数 情况 的 需求 ， 但 对 这 个 多 对 多 关系 来 说 却 不 合适 。 删 除 对 象 时 ， 默 认 的 层 
示 行 为 是 把 对 象 连接 的 所 有 相关 对 象 的 外 键 设 为 空 值 。 但 在 关联 表 中 ， 删 除 记录 后 正确 
的 行为 应 该 是 把 指向 该 记录 的 实体 也 删除 ， 这 样 才能 有 效 销毁 连接 。 这 就 是 层 琶 选项 值 
delete-orphan 的 作用 。 

cascade 参数 的 值 是 一 组 由 逗号 分 隔 的 层 芭 选项， 其 中 all 表示 除了 delete- 


orphan 之 外 的 所 有 层 又 选项 ， 这 看 起 来 可 能 让 人 有 点 困惑 。 设 为 all， 
delete-orphan 的 意思 是 启用 所 有 默认 层 垒 选项， 而 且 还 要 删除 孤儿 记录 。 






































应 用 现在 要 处 理 两 个 一 对 多 关系 ， 以 便 实 现 多 对 多 关系 。 由 于 这 些 操作 经 常 需要 重复 执 
行 ， 所 以 最 好 在 User 模型 中 为 所 有 可 能 的 操作 定义 辅助 方法 。 用 于 控制 关系 的 4 个 新 方法 
如 示例 12-3 所 示 。 


示例 12-3 app/models.py: 关注 关系 的 辅助 方法 
class User(db.Model): 
He 
def follow(self, user): 
if not self.is_ following(user): 
f = Follow(follower=self, followed=user) 
db.session.add(f) 








def unfollow(self, user): 
f = self.followed.filter_by(followed_id=user .id).first() 
if f: 
db.session.delete(f) 


def is following(self, user): 
if user.id is None: 
return False 
return self.followed.filter_by( 
followed_ id=user .id).first() is not None 


def is_ followed_ by(self, user): 
if user.id is None: 
return False 
return self.followers.filter_by( 
follower_id=user .id).first() is not None 


follow() 方法 手动 把 FoLLow 实例 插入 关联 表 ， 从 而 把 关注 者 和 被 关注 者 连接 起 来 ， 并 让 
应 用 有 机 会 设 定 自 定义 字段 。 连 接 在 一 起 的 两 个 用 户 被 手动 传人 Follow 类 的 构造 器 ， 创 
建 一 个 FoLtLow 新 实例 ， 然 后 像 往常 一 样 ， 把 这 个 实例 对 象 添 加 到 数据 库 会 话 中 。 注 意 ， 
这 里 无 需 手动 设 定 timestamp 字段 ， 因 为 定义 字段 时 指定 了 默认 值 ， 即 当前 日 期 和 时 间 。 
unfollow() 方法 使 用 followed 关系 找到 连接 用 户 和 被 关注 用 户 的 FoLLow 实例 。 若 要 销 
毁 这 两 个 用 户 之 间 的 连接 ， 只 需 删 除 这 个 Follow 对 象 即 可 。is_following() 方法 和 is_ 
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followed_by() 方法 分 别 在 左右 两 边 的 一 对 多 关系 中 搜索 指定 用 户 ， 如 果 找 到 了 就 返回 
True。 发 起 查询 之 前 ， 这 两 个 方法 都 确认 了 指定 的 用 户 有 没有 td， 以 防 创建 了 用 户 ， 但 是 
尚未 提交 到 数据 库 。 


如 果 你 从 GitHub 上 克隆 了 这 个 应 用 的 Git 仓库 ， 那 么 可 以 执行 git checkout 
12a 检 出 应 用 的 这 个 版 本 。 这 个 版 本 包含 一 个 数据 库 迁 移 ， 检 出 代码 后 记得 














要 执行 fLask db upgrade 命令 。 


现在 ， 关 注 功 能 在 数据 库 中 的 部 分 完成 了 。 你 可 以 在 GitHub 上 的 源码 仓库 找到 对 于 这 个 
数据 库 关 系 的 单元 测试 。 


12 








.2 ”在 资料 页 面 中 显示 关注 者 








如 果 用 户 查 看 一 个 尚未 关注 用 户 的 资料 页 面 ， 页 面 中 要 显示 一 个 “Follow”( 关 注 ) 按钮， 
如 果 查 看 已 关注 用 户 的 资料 页 面 则 显示 “Unfollow”( 取 消 关 注 ) 按钮 。 而 且 ， 页 


能 显示 H 
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而 中 最 好 






































所 示 。 添 加 这 些 信息 后 的 资料 页 面 如 图 12-3 所 示 。 
示例 12-4 app/templates/user.html: 在 用 户 资 料 页 面 上 部 添加 关注 信息 


{% if current_user.can(Permission.FOLLOW) and user != current_user %} 
{% if not current user.is following(user) %} 
<a href="{{ url_for('.follow', username=user .username) }}" 
class="btn btn-primary">FoLLow</a> 
{% else %} 
<a href="{{ url_for('.unfollow', username=user .username) }}" 
class="btn btn-default">Unfollow</a> 
{% endif %} 
{% endif %} 
<a href="{{ url_for('.followers', username=user .username) }}"> 
Followers: <span class="badge">{{ user.followers.count() }}</span> 
</a> 
<a href="{{ url_for('.followed_by', username=user .username) }}"> 
Following: <span class="badge">{{ user.foLLowed.count() }}</span> 
</a> 
{% if current user.is authenticated and user != current_ user and 
user.is_following(current_user) %} 
| <span class="label label-default">Follows you</span> 
{% endif %} 


关注 者 和 被 关注 者 的 数量 ， 再 列 出 关注 和 被 关注 的 用 户 列 表 ， 并 在 相应 的 用 户 资 
看 中 显示 “Follows You”( 关 注 了 你 ) 标志 。 对 用 户 资料 页 面 模 板 的 改动 如 示例 12-4 
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12-3: 


资料 页 中 显示 的 关注 信息 





这 次 修改 模板 用 到 了 4 个 新 端点 。 用 户 在 其 他 用 户 的 资料 页 面 中 点 击 “Follow” (关注 ) 按 
钮 后 ， 调 用 的 是 /follow/<username> 路 由 。 这 个 路 由 的 实现 如 示例 12-5 所 示 。 


示例 12-5 app/main/views.py:“ 关 广 ” 路 由 和 视图 函数 
Q@main.route(' /foLLow/<username> ' ) 
@login_required 
@permission_required(Permission.FOLLOW) 
def follow(username): 


这 个 视 





图 函数 先 加 载 请 求 的 用 户 ， 确 保 用 户 存 在 且 当 前 登录 用 户 还 没有 关注 这 个 用 户 ， 然 











user = User.query.filter_by(username=username).first() 
if user is None: 
flash('Invalid user.') 
return redirect(url_for('.index')) 
if current _user.is_ following(user): 
flash('You are already following this user.') 
return redirect(url_for('.user', username=username)) 
current_user.follow(user) 
db.session.commit() 
flash('You are now following %s.' % username) 
return redirect(url for('.user', Username=username)) 








后 调用 User 模型 中 定义 的 辅助 方法 follow()， 连 接 两 个 用 户 。/unfollow/<username> 路 由 
的 实现 方式 类 似 。 


用 户 在 其 他 用 户 的 资料 页 中 点 击 关注 者 数量 后 ， 将 调用 /followers/<username> 路 由 。 这 个 
路 由 的 实现 如 示例 12-6 所 示 。 








示例 12-6 ”app/main/views.py:“ 关 注 者 ”路 由 和 视图 函数 
@main.route('/followers/<username>') 
def followers(username): 
user = User.query.filter_by(username=username).first() 
if user is None: 
flash('Invalid user.') 
return redirect(url_ for('.index')) 
page = request.args.get('page', 1, type=int) 
pagination = User.foLLowers.paginate( 
page, per_page=current_app.config['FLASKY_FOLLOWERS_PER_PAGE'], 
error_out=False) 
foLLows = [{'user': item.follower, 'timestamp': item.timestamp} 
for item in pagination.items] 
return render_template('followers.html', user=user, title="Followers of", 
endpoint="' .followers', pagination=pagination, 
follows=follows) 


这 个 函数 加 载 并 验证 请 求 的 用 户 ， 然 后 使 用 第 11 章 中 介绍 的 技术 分 页 显示 该 用 户 的 
followers 关系 。 由 于 查询 关注 者 返回 的 是 Follow 实例 列表 ， 为 了 泻 染 方便 ， 我 们 将 其 转 
换 成 一 个 新 列表 ， 列 表 中 的 各 元 素 都 包含 user 和 timestamp 字段 。 

泻 染 关注 者 列表 的 模板 可 以 写 的 通用 一 些 ， 以 便 能 用 来 泻 染 关注 的 用 户 列表 和 被 关注 的 用 
户 列表 。 模 板 接收 的 参数 包括 用 户 对 象 、 页 面 的 标题 、 分 页 链接 使 用 的 端点 、 分 页 对 象 和 
查询 结果 列表 。 


foLLowed_by 端点 的 实现 过 程 几乎 一 样 ， 唯 一 区 别 在 于 ， 用 户 列 表 从 user.foLLowed 关系 中 
获取 。 传 入 模板 的 参数 也 要 进行 相应 调整 。 

followers.html 模板 使 用 两 列表 格 实现 ， 左 边 一 列 显示 用 户 名 和 头像 ， 右 边 一 列 显示 Flask- 
Moment 时 间 惟 。 有 具体 的 实现 代码 参见 GitHub 源码 仓库 。 









































如 果 你 从 GitHub 上 克隆 了 这 个 应 用 的 Git 仓库 ， 那 么 可 以 执行 git checkout 
12b 检 出 应 用 的 这 个 版 本 。 








米 A A < 二 二 = 
12.3 ”使 用 数据 库 联结 查询 所 关注 用 户 的 文章 

应 用 首页 目前 按时 间 降 序 显示 数据 库 中 的 所 有 文章 。 现 在 我 们 已 经 完成 了 关注 功能 ， 如 果 
只 查看 所 关注 用 户 发 布 的 博客 文章 就 更 好 了 。 

若 想 显示 所 关注 用 户 发 布 的 所 有 文章 ， 第 一 步 显 然 先 要 获取 这 些 用 户 ， 然 后 获取 各 用 户 的 
文章 ， 再 按 一 定 顺序 排列 ， 写 入 一 个 列表 。 可 是 这 种 方式 的 伸缩 性 不 好 ， 随 着 数据 库 不 断 
变 大 ， 生 成 这 个 列表 的 工作 量 也 不 断 增 长 ， 而 且 分 页 等 操作 也 无 法 高 效 完成 。 这 是 一 个 常 
见 的 问题 ， 人 们 称 之 为 “N+1 问题 ”， 因 为 这 里 需要 发 起 N+1 次 数据 库 查 询 ， 其 中 入 是 第 
一 次 查询 返回 的 结果 数量 。 高 效 获取 博客 文章 ， 而 不 管 数据 库 有 多 大 ， 最 好 的 方法 是 在 一 
次 查询 中 完成 所 有 操作 。 
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完成 这 个 操作 的 数据 库 操作 称 为 联结 。 联 结 操作 用 到 两 个 或 更 多 的 数据 表 ， 在 其 中 查找 满 
足 指 定 条 件 的 记录 组 合 ， 再 把 记录 组 合 插入 一 个 临时 表 中 ， 这 个 临时 表 就 是 联结 查询 的 结 
果 。 理 解 联结 查询 的 最 好 方法 是 实例 讲解 。 


表 12-1 是 一 个 users 表示 例 ， 表 中 有 3 个 用 户 。 
表 12-1: users 表 

















id Username 
1 john 

2 susan 

3 david 


表 12-2 是 对 应 的 posts 表 ， 表 中 有 几 篇 博客 文章 。 
表 12-2: posts 表 





id author_id body 

1 2 susan 发 布 的 博客 文章 

2 1 john 发 布 的 博客 文章 

3 3 david 发 布 的 博客 文章 

4 1 john 发 布 的 第 2 篇 博客 文章 








最 后 ， 表 12-3 显示 谁 关 注 了 谁 。 从 这 个 表 中 可 以 看 出 ，john 关注 了 david，susan 关注 了 john 
和 david， 但 david 谁 也 没 关 注 。 
表 12-3，follows 表 





follower_id followed_id 
1 3 
作 1 
2 3 





若 想 获得 susan 所 关注 用 户 发 布 的 文章 ， 必 须 合并 posts 表 和 follows 表 。 首 先 过 滤 follows 
表 ， 只 留 下 关注 者 为 susan 的 记录 ， 即 上 面 表 中 的 最 后 两 行 。 然 后 过 滤 posts 表 ， 留 下 
author_id 和 过 滤 后 的 follows 表 中 foLLowed_id 相等 的 记录 ， 把 两 次 过 滤 结 果 合 并 ,组 成 
临时 联结 表 ， 这 样 就 能 高 效 查 询 susan 所 关注 用 户 发 布 的 文章 列表 。 表 12-4 是 此 次 联结 操 
作 得 到 的 结果 。 用 于 执行 此 次 联结 操作 的 列 在 表 中 加 上 了 * 标记 。 















































表 12-4: 联结 表 

id author_id* body follower_id foLLowed id* 

2 1 john 发 布 的 博客 文章 2 1 

3 3 david 发 布 的 博客 文章 2 3 

4 1 john 发 布 的 第 2 篇 博客 文章 9 1 
这 个 表 中 包含 的 博客 文章 都 是 用 户 susan 所 关注 用 户 发 布 的 。 使 用 Flask-SQLAlchemy 执行 
这 个 联结 操作 的 查询 相当 复杂 : 
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return db.session.query(Post).select from(Follow).\ 
filter_by(follower_id=self.id).\ 
join(Post, Follow.followed id == Post.author_id) 


你 在 此 之 前 见 到 的 查询 都 是 从 所 查询 模型 的 query 属性 开始 的 。 这 里 不 能 这 样 做 ， 因 为 查 

询 要 返回 posts 记录 ， 所 以 首先 要 做 的 操作 是 在 foLLows 表 上 执行 过 滤器 。 因 此 ， 这 里 使 

用 了 一 种 更 基础 的 查询 方式 。 为 了 完全 理解 上 述 查 询 ， 下 面 分 别 说 明 各 部 分 : 

。 db.session.query(Post) 指明 这 个 查询 将 返回 Post 对 象 ; 

。 select_from(Follow) 的 意思 是 这 个 查询 从 Follow 模型 开始 ; 

。 filter_by(follower_id=self.id) 使 用 关注 用 户 过 滤 foLLows 表 ; 

。 join(Post，Follow.followed_id == Post.author_id) 联结 filter_by() 得 到 的 结果 和 
Post 对 象 。 


调换 过 滤器 和 联结 的 顺序 可 以 简化 这 个 查询 : 


return Post.query.join(Follow, Follow.followed id == Post.author_id)\ 
.filter(Follow.follower_id == self.id) 


如 果 首 先 执 行 联结 操作 ， 那 么 这 个 查询 就 可 以 从 Post.query 开始 ， 此 时 唯一 需要 使 用 的 
两 个 过 滤器 是 join() 和 filter()。 先 执行 联结 操作 再 过 滤 看 起 来 工作 量 会 更 大 一 些 ,， 但 
实际 上 这 两 种 查询 是 等 效 的 。SQLAlchemy 首先 收集 所 有 过 滤器 ， 然 后 再 以 最 高 效 的 方 
式 生成 查询 。 这 两 种 查询 生成 的 原生 SQL 指令 几乎 一 样 。 如 果 不 信 ， 可 以 把 查询 对 象 
转换 成 字符 串 看 看 (print(str(query)))。 我 们 要 把 后 一 种 查询 写 和 人 Post 模型 ， 如 示例 
12-7 所 示 。 


示例 12-7 app/models.py: 获取 所 关注 用 户 的 文章 
class User(db.Model): 
i 
@property 
def followed_ posts(self): 
return Post.query.join(Follow, Follow.followed_id == Post.author_id)\ 
.filter(Follow.follower_id == self.id) 


注意 ，foLLowed_posts() 方法 定义 为 属性 ， 因 此 调用 时 无 需 加 ()。 如 此 一 来 ， 所 有 关系 的 
句法 都 一 样 了 。 


























如 果 你 从 GitHub 上 克隆 了 这 个 应 用 的 Git 仓库 ， 那 么 可 以 执行 git checkout 
12c 检 出 应 用 的 这 个 版 本 。 











联结 非常 难 理解 ， 你 可 能 需要 在 shell 中 多 研究 一 下 示例 代码 才能 完全 领悟 。 


12.4 在 首页 显示 所 关注 用 户 的 文章 


现在 ， 用 户 可 以 选择 在 首页 显示 所 有 用 户 的 博客 文章 还 是 只 显示 所 关注 用 户 的 文章 了 。 示 
例 12-8 展示 如 何 实 现 这 种 选择 。 


了 
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\ 


示例 12-8 ”app/main/views.py: 显示 所 有 博客 文章 
@main.route('/', methods = ['GET', 'POST']) 
def index(): 
Hs 
show_followed = False 
if current_user.is_authenticated: 
show_followed = bool(request.cookies.get('show followed', '')) 
if show_followed: 
query = current_user.followed posts 
else: 
query = Post.query 
pagination = query.order_by(Post.timestamp.desc()).paginate( 
page, per_page=current_app.config['FLASKY_POSTS_PER_PAGE'], 
error_out=False) 
posts = pagination.items 
return render_template('index.html', form=form, posts=posts, 


show_followed=show_followed, pagination=pagination) 


决定 显示 所 有 博客 文章 还 是 只 显示 所 关注 用 户 文章 的 选项 存储 在 名 为 show_followed 自 
cookie 中 ， 如 果 其 值 为 非 空 字 符 串 ， 表 示 只 显示 所 关注 用 户 的 文章 。cookie 以 request. 
cookies 字典 的 形式 存储 在 请 求 对 象 中 。 这 个 cookie 的 值 会 转换 成 布尔 值 ， 根 据 得 到 的 值 






































或 只 显示 所 关注 用 户 的 文章 


和 











I 





设 定 本 地 变量 query 的 值 。query 的 值 决 定 最 终 获 取 所 有 博客 文章 的 查询 ， 还 是 获取 过 滤 
后 的 博客 文章 查询 。 显 示 所 有 用 户 的 文章 时 ， 要 使 用 顶级 查询 Post .query;， 如 果 限 制 只 























显示 所 关注 用 户 的 文章 ， 要 使 用 最 近 添 加 的 User.foLLowed_posts 属性 。 然 后 将 局 部 变 





query 中 保存 的 查询 进行 分 页 ， 像 往常 一 样 将 其 传 入 模板 。 
show_followed cookie 在 两 个 新 路 由 中 设 定 ， 如 示例 12-9 所 示 。 


示例 12-9 app/main/views.py: 查询 所 有 文章 还 是 所 关注 用 户 的 文章 
@main.route('/all') 
@login_required 
def show_all(): 
resp = make_response(redirect(url_for('.index'))) 
resp.set_cookie('show_followed', '', max_age=30*24*60*60) # 30 天 
return resp 








@main.route('/followed') 

@login_required 

def show_followed(): 
resp = make_response(redirect(url_for('.index'))) 
resp.set_cookie('show_followed', '1', max_age=30*24*60*60) # 30 天 
return resp 


-是 - 
目 





指向 这 两 个 路 由 的 链接 添加 在 首页 模板 中 。 点 击 这 两 个 链接 后 会 为 show_followed cookie 





设 定 适 当 的 值 ， 然 后 重 定向 到 首页 。 








cookie 只 能 在 响应 对 象 中 设置 ， 因 此 这 两 个 路 由 不 能 依赖 Flask， 要 使 用 make_response() 








方法 创建 响应 对 象 。 


set_cookie() 函数 的 前 两 个 参数 分 别 是 cookie 名 称 和 值 。 可 选 的 max_age 参数 设置 cookie 
的 过 期 时 间 ， 单 位 为 秒 。 如 果 不 指 定 max_age 参数 ， 浏 览 器 关闭 后 cookie 就 会 过 期 。 在 本 








例 中 ， 最 长 过 期 时 间 为 30 天 ， 所 以 即便 用 户 几 天 不 访问 应 用 ， 浏 览 器 也 会 记 住 设 定 的 值 。 
接 下 来 我 们 要 对 模板 做 些 改动 ， 在 页 面 上 部 添加 两 个 导航 选项 卡 ， 分 别 调用 /all 和/ 
followed 路 由 ， 并 在 会 话 中 设 定 正确 的 值 。 你 可 在 GitHub 上 的 源码 仓库 中 查看 模板 改动 详 
情 。 改 动 后 的 首页 如 图 12-4 所 示 。 




















ee 亲 Faso 


€ CG 合 @Iiocalhost:5000 





Hello, john! 


What's on your mind? 


Submit 
All Followed 
YE wespinoza 4 days ago 
4 Maiores illo non doloremque ratione delectus. Facilis officiis corporis nihil perferendis occaecati odio et 
explicabo. 
YE wespinoza 25 days ago 
多 和 Voluptate deserunt ipsam veniam rerum aut. Quasi odio maxime occaecati repudiandae fugit cumque. 


Hic quaerat suscipit beatae magni ad dolor optio. lure ad officiis cum distinctio dolor. 











图 12-4: 首页 中 所 关注 用 户 发 布 的 文章 


如 果 你 从 GitHub 上 克隆 了 这 个 应 用 的 Git 仓库 ， 那 么 可 以 执行 git checkout 
12d 检 出 应 用 的 这 个 版 本 。 








如 果 你 现在 访问 网 站 ， 切 换 到 所 关注 用 户 文章 列表 ， 会 发 现 自己 的 文章 不 在 列表 中 。 这 是 

肯定 的 ， 因 为 用 户 不 能 关注 自己 。 

虽然 查询 能 按 设计 正常 执行 ， 但 用户 查 看 好 友 文 章 时 还 是 希望 能 看 到 自己 的 文章 。 这 个 问 
题 最 简单 的 解决 办 法 是 ， 注 册 时 把 用 户 设 为 自己 的 关注 者 。 实 现 方法 如 示例 12-10 所 示 。 
示例 12-10 app/models.py: 创建 用 户 时 把 用 户 设 为 自己 的 关注 者 


class User(UserMixin, db.Model): 








i 

def _ init_ (self, **kwargs): 
# ... 

self.follow(self) 
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可 是 ， 现 在 数据 库 中 可 能 已 经 有 一 些 用 户 ， 而 且 都 没有 关注 自己 。 如 果 数 据 库 还 比较 小 ， 
容易 重新 生成 ， 那 么 可 以 删 掉 再 重新 创建 。 如 果 情 况 相 反 ， 那 么 正确 的 方法 是 添加 一 个 函 
数 ， 更 新 现 有 用 户 ， 如 示例 12-11 所 示 。 


示例 12-11 app/models.py: 把 用 户 设 为 自己 的 关注 者 
class User(UserMixin, db.Model): 
# 
@staticmethod 
def add_self_follows(): 
for user in User.query.all(): 
if not user.is following(user): 
user.follow(user) 
db.session.add(user) 
db.session.commit() 


























A 


现在 ， 可 以 在 shell 中 运行 这 个 函数 ， 更 新 数据 库 : 


(venv) $ flask shell 
>>> User .add_self_follows() 


创建 函数 更 新 数据 库 这 一 技术 经 常用 来 更 新 已 部 署 的 应 用 ， 因 为 运行 脚本 更 新 比 手动 更 新 
数据 库 更 少 出 错 。 在 第 17 章 ， 你 将 看 到 如 何在 部 署 脚本 中 使 用 这 个 函数 及 类 似 的 函数 。 
用 户 关注 自己 这 一 功能 的 实现 让 应 用 变 得 更 实用 ,但 也 有 一 些 副 作用 。 因 为 用 户 关注 了 自 
己 ， 用 户 资 料 页 面 显示 的 关注 者 和 被 关注 者 的 数量 都 增加 了 1 个。 为 了 显示 准确 ， 这 些 数 
字 要 减 去 1， 这 一 点 在 模板 中 很 容易 实现 ， 直 接 泻 染 {{ user.followers.count() - 1 }} 和 
{{ user.followed.count() - 1 坟 即 可 。 此 外 ， 还 要 调整 关注 用 户 和 被 关注 用 户 的 列表 ， 
不 显示 自己 。 这 在 模板 中 也 容易 实现 ， 使 用 条 件 语句 即 可 。 最 后 ， 检 查 关 注 者 数量 的 单元 
测试 也 会 受到 自 关注 的 影响 ， 必 须 适当 调整 ， 考 虑 自 关注 。 























如 果 你 从 GitHub 上 克隆 了 这 个 应 用 的 Git 仓库 ， 那 么 可 以 执行 gtt checkout 
12e 检 出 应 用 的 这 个 版 本 。 





下 一 章 将 实现 用 户 评论 子 系统 ， 这 是 社交 应 用 的 另 一 个 重要 功能 。 
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允许 用 户 交 互 是 社交 博客 平台 成 功 的 关键 。 在 本 章 ， 你 将 学 到 如 何 实 现 用 户 评 论 功能 。 这 
里 介绍 的 技术 基本 上 可 以 直接 用 在 大 多 数 社交 应 用 中 。 


13.1 评论 在 数据 库 中 的 表示 


评论 和 博客 文章 没有 太 大 区 别 ， 都 有 正文 、 作 者 和 时 间 惟 ， 而 且 在 这 个 特定 实现 中 都 使 用 
Markdown 句法 编写 。 图 13-1 是 comments 表 的 图 解 及 其 与 其 他 数据 表 之 间 的 关系 。 


Users comments 


id id 
Username body 
要 body_html 


timestamp 
author_id 
post_id 












































13-1: 博客 文章 评论 的 数据 库 表 示 

评论 属于 某 篇 博客 文章 ， 因 此 定义 了 一 个 从 posts 表 到 comments 表 的 一 对 多 关系 。 使 用 这 
个 关系 可 以 获取 基 篇 博客 文章 的 评论 列表 。 

comments 表 还 与 users 表 之 间 有 一 对 多 关系 。 通 过 这 个 关系 可 以 获取 用 户 发 表 的 所 有 评论 ， 


还 能 间接 知道 用 户 发 表 了 多 少 篇 评论 。 用 户 发 表 的 评论 数量 可 以 显示 在 用 户 资料 页 面 中 。 
Comment 模型 的 定义 如 示例 13-1。 
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示例 13-1 app/models.py: Comment 模型 


class Comment(db.Model): 
_tablename _ = 'comments' 
id = db.Column(db.Integer, primary_key=True) 
body = db.Column(db.Text) 
body_html = db.Column(db.Text) 
timestamp = db.Column(db.DateTime, index=True, default=datetime.utcnow) 
disabled = db.Column(db.Boolean) 
author_id = db.Column(db.Integer, db.ForeignKey('users.id')) 
post_id = db.Column(db.Integer, db.ForeignKey('posts.id')) 


@staticmethod 
def on_changed_body(target, value, oldvalue, initiator): 
allowed tags = ['a', 'abbr', 'acronym', 'b', 'code', 
'strong'] 
target.body_html = bleach.linkify(bleach.clean( 
markdown(vaLue，output_format= 'htmL' ) ， 
tags=allowed_tags, strip=True)) 


em', 'i', 


db.event.listen(Comment.body, 'set', Comment.on_changed_body) 


Comment 模型 的 属性 几乎 和 Post 模型 一 样 ， 不 过 多 了 一 个 disabled 字段 。 这 是 个 布尔 值 字 
段 ， 协 管 员 通过 这 个 字段 查禁 不 当 评论 。 与 博客 文章 一 样 ， 评 论 也 定义 了 一 个 事件 ， 在 修 
改 body 字段 内 容 时 触发 ， 自 动 把 Markdown 文本 转换 成 HIML。 转 换 过程 和 第 11 章 中 的 
博客 文章 一 样 ， 不 过 评论 相对 较 短 ， 而 且 对 Markdown 中 允许 使 用 的 HTML 标签 要 求 更 严 
格 ， 要 删除 与 段落 相关 的 标签 ， 只 留 下 格式 化 字符 的 标签 。 


为 了 完成 对 数据 库 的 修改 ，User 和 Post 模型 还 要 建立 与 comments 表 的 一 对 多 关系 ， 如 示 
例 13-2 所 示 。 


示例 13-2 app/models.py: users 和 posts 表 与 comments 表 之 间 的 一 对 多 关系 


class User(db.Model): 
革 
comments = db.relationship('Comment', backref='author', lazy='dynamic') 


















































class Post(db.Model): 
es 
comments = db.relationship('Comment', backref='post', lazy='dynamic') 


13.2 提交 和 显示 评论 


在 这 个 应 用 中 ,评论 显示 在 单 篇 博客 文章 页 面 中 。 这 些 页 面 在 第 11 章 添 加 固定 链接 时 已 
经 创建 。 在 这 些 页 面 中 还 要 有 一 个 提交 评论 的 表单 。 用 来 输入 评论 的 表单 如 示例 13-3 所 
示 。 这 个 表单 很 简单 ， 只 有 一 个 文本 字段 和 一 个 提交 按钮 。 


示例 13-3 ”app/main/forms.py: 评论 输入 表单 


class CommentForm(FLaskForm) : 
body = StringField('', validators=[DataRequired()]) 
submit = SubmitField('Submit') 


为 了 支持 评论 ，/post/<int:id> 路 由 要 做 些 修改 ， 如 示例 13-4 所 示 。 









































和 E> 
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示例 13-4 app/main/views.py: 支持 博客 文章 评论 
@main.route('/post/<int:id>', methods=['GET', 'POST']) 
def post(id): 
post = Post.query.get or_404(id) 
form = CommentForm() 
if form.validate on_submit(): 
Comment = Comment(body=form.body.data, 
post=post， 
author=current_uUser. get_current_object()) 
db.session.add(comment) 
db.session.commit() 
flash('Your comment has been published.') 
return redirect(url_ for('.post', id=post.id, page=-1)) 
page = request.args.get('page', 1, type=int) 
if page == -1: 
page = (post.comments.count() - 1) //\ 
current_app.config['FLASKY_COMMENTS_PER_PAGE'] + 1 
pagination = post.comments.order_by(Comment.timestamp.asc()).paginate( 
page, per_page=current _app.config['FLASKY_COMMENTS_PER_PAGE'], 
error_out=False) 
comments = pagination.items 
return render_template('post.html', posts=[post], form=form, 
comments=comments, pagination=pagination) 


这 个 视图 函数 实例 化 一 个 评论 表单 ， 将 其 转 入 post.html 模板 ， 以 便 演 染 。 提 交 表 单 后 ， 插 
入 新 评论 的 逻辑 与 处 理 博客 文章 的 过 程 差不多 。 和 Post 模型 一 样 ， 评 论 的 author 字段 也 
不 能 直接 设 为 current_user， 因 为 这 个 变量 是 上 下 文 代理 对 象 。 真 正 的 User 对 象 要 使 用 表 






































达 式 current_user._get_current_object() 获取 。 

















评论 按照 时 间 惟 顺序 排列 ， 新 评论 显示 在 列表 的 底部 。 提 交 评 论 后 ， 请 求 结 采 是 一 个 重 定 
向 ， 转 回 之 前 的 URL， 但 是 在 urL_for() 函数 的 参数 中 把 page 设 为 -1， 这 是 个 特殊 的 页 

















数 ， 用 于 请 求 评论 的 最 后 一 页 ， 所 以 刚 提 交 的 评论 才 会 出 现在 页 面 中 。 应 用 从 查询 字符 











Ud 


中 获取 页 数 ， 发 现 值 为 -1 时, 会 计算 评论 的 总 量 和 总 页 数 ， 得 出 真正 要 显示 的 页 数 。 


文章 的 评论 列表 通过 post.comments 一 对 多 关系 获取 ， 按 照 时 间 礁 顺序 排列 ， 再 使 用 与 博客 
文章 相同 的 技术 分 页 显示 。 评 论 列表 对 象 和 分 页 对 象 都 要 传人 模板 ， 以 便 泻 染 。 此 外 ， 还 要 
在 config.py 中 添加 FLASKY_COMMENTS_PER_PAGE 配置 变量 ， 用 于 控制 每 页 显示 的 评论 数量 。 


评论 在 新 模板 _comments.html 中 泻 染 ， 这 个 模板 的 内 容 类 似 于 _posts.html， 但 使 用 的 CSS 






































类 不 同 。_comments.html 模板 在 _posts.html 中 引入 ， 放 在 文章 正文 下 方 ， 后 面 再 i 
宏 。 对 模板 的 改动 参见 GitHub 中 本 应 用 的 仓库 。 








uy 








周 用 分 页 


为 了 完善 功能 ， 我 们 还 要 在 首页 和 资料 页 面 加 上 指向 评论 页 面 的 链接 ， 如 示例 13-5 所 示 。 











示例 13-5 ”app/templates/_posts.html: 链接 到 博客 文章 的 评论 


<a href="{{ url_for('.post', id=post.id) }}#comments"> 
<span class="label label-primary"> 
{{ post.comments.count() }} Comments 
</span> 
</a> 
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注意 ， 链 接 文本 中 有 评论 的 数量 。 评 论 数量 可 以 使 用 SQLAlchemy 提供 的 count() 过 滤器 
轻松 地 从 posts 和 comments 表 的 一 对 多 关系 中 获取 。 


指向 评论 页 的 链接 结构 也 值得 一 说 。 这 个 链接 的 地 址 是 在 文章 的 固定 链接 后 面 加 上 
#comments 后 级 。 这 个 后 级 称 为 URL 片段 ， 用 于 指定 加 载 页面 后 滚动 条 所 在 的 初始 位 置 。 
Web 浏览 器 会 寻找 id 等 于 URL 片段 的 元 素 并 滚动 页 面 ， 让 这 个 元 素 显示 在 窗口 顶部 。 
在 post.html 模板 中 ， 滚 动 条 的 初始 位 置 被 设 为 “Comments” 标 题 ， 其 HTML 代码 为 <h4 
id="comments">Comments</h4>。 显 示 有 评论 的 页 面 如 图 13-2 所 示 。 











@@ WM Flasky-Post 


二 C 合 @Iocalhost:5000 t/14? 





所 wespinoza 25 days ago 
时 六 Excepturi at ea maiores. Consequatur exercitationem aliquam quisquam illo. Neque vel assumenda quod 
delectus saepe hic impedit alias. 
ED EE 
Comments 
Enter your comment 
Submit 
john afew seconds ago 
Great article! 














图 13-2: 博客 文章 的 评论 


除 此 之 外 ， 分 页 导航 所 用 的 宏 也 要 做 些 改动 。 评 论 的 分 页 导航 链接 也 要 加 上 #comments 片 
段 ， 因 此 在 post.html 模板 中 调用 宏 时 ， 要 传人 片段 参数 。 


如 果 你 从 GitHub 上 克隆 了 这 个 应 用 的 Git 仓库 ， 那 么 可 以 执行 git checkout 
13a 检 出 应 用 的 这 个 版 本 。 这 个 版 本 包含 一 个 数据 库 迁 移 ， 检 出 代码 后 记得 
要 执行 fLask db upgrade 命令 。 





13.3 管理 评论 

我 们 在 第 9 章 定义 了 几 个 用 户 角 色 ， 它 们 分 别 具 有 不 同 的 权限 。 其 中 一 个 权限 是 Permission . 
MODERATE， 拥 有 此 权限 的 用 户 可 以 管理 其 他 用 户 的 评论 。 

为 了 管理 评论 ， 我 们 要 在 导航 栏 中 添加 一 个 链接 ， 具 有 此 项 权限 的 用 户 才能 看 到 。 这 个 链 
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接 在 base.html 模板 中 使 用 条 件 语 句 添 加 ， 如 示例 13-6 所 示 。 
示例 13-6 ”app/templates/base.html: 在 导航 条 中 加 入 管理 评论 链接 








{% if current_user.can(Permission.MODERATE) %} 
<li><a href="{{ url_for('main.moderate') }}">Moderate Comments</a></li> 
{% endif %} 


管理 页 面 中 有 个 列表 显示 全 部 文章 的 评论 ， 而 且 最 近 发 表 的 评论 显示 在 前 面 。 每 篇 评论 的 
下 方 都 会 显示 一 个 按钮 ， 用 来 切换 disabled 属性 的 值 。/moderate 路 由 的 定义 如 示例 13-7 
所 示 。 


示例 13-7 app/main/views.py: 管理 评论 的 路 由 
@main.route('/moderate') 
@login_required 
@permission_required(Permission.MODERATE) 
def moderate() : 
page = request.args.get('page', 1, type=int) 
pagination = Comment.query.order_by(Comment.timestamp.desc()).paginate( 
page, per_page=current _app.config['FLASKY_COMMENTS_PER_PAGE'], 
error_out=False) 
comments = pagination.items 
return render_template('moderate.html', comments=comments, 
pagination=pagination, page=page) 


这 个 函数 很 简单 ， 它 从 数据 库 中 读 取 一 页 评论 ， 将 其 传人 模板 进行 渲染 。 除 了 评论 列表 之 
外 ， 还 把 分 页 对 象 和 当前 页 数 传人 了 模板 。 

moderate.html 模板 也 很 简单 ， 如 示例 13-8 所 示 ， 它 依靠 之 前 创建 的 子 模板 _comments.html 
泻 染 评论 。 
示例 13-8 ”app/templates/moderate.html: 评论 管理 页 面 的 模板 


{% extends "base.html" %} 
{% import "_macros.html" as macros %} 











{% block title %}Flasky - Comment Moderation{% endblock %} 


{% block page_content %} 
<div class="page-header"> 
<h1>Comment Moderation</h1> 
</div> 
{% set moderate = True %} 
{% incLude '_comments.html' %} 
{% if pagination %} 
<div class="pagination"> 
{{ macros.pagination widget(pagination, '.moderate') }} 
</div> 
{% endif %} 
{% endblock %} 


这 个 模板 将 泻 染 评论 的 工作 交 给 _comments.html 模板 完成 ， 但 把 控制 权 交 给 从 属 模板 之 
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前 ， 会 使 用 Jinja2 提供 的 set 指令 定义 一 个 模板 变量 noderate， 并 将 其 值 设 为 True。 这 个 





变量 用 在 _comments.html 模板 中 ， 决 定 是 否 泻 染 评论 管理 功能 。 








_comments.html 模板 中 显示 评论 正文 的 部 分 要 做 两 方面 修改 。 对 于 普通 用 户 (未 设 定 
moderate 变量 )， 不 显示 标记 为 有 问题 的 评论 。 对 于 协 管 员 (moderate 设 为 True)， 不 管 评 
论 是 否 被 标记 为 有 问题 ， 都 要 显示 ， 而 且 在 正文 下 方 还 要 显示 一 个 用 来 切换 状态 的 按钮 。 





具体 的 改动 如 示例 13-9 所 示 。 


示例 13-9 ”app/templates/_comments.html: 浑 染 评论 的 正文 


<div class="comment-body"> 
{% if comment.disabled %} 
<p></p><i>This comment has been disabled by a moderator.</i></p> 
{% endif %} 
{% if moderate or not comment.disabled %} 
{% if comment.body_html %} 
{{ comment.body_htmL | safe }} 
{% else %} 
{{ comment.body }} 
{% endif %} 
{% endif %} 
</div> 
{% if moderate %} 
<br> 
{% if comment.disabled %} 


<a class="btn btn-default btn-xs" href="{{ url_for('.moderate enable', 


id=comment.id, page=page) }}">Enable</a> 
{% else %} 


<a class="btn btn-danger btn-xs" href="{{ url_for('.moderate disable', 


id=comment.id, page=page) }}">Disable</a> 
{% endif %} 
{% endif %} 








做 了 上 述 改 动 之 后 ， 用 户 将 看 到 一 个 关于 有 问题 评论 的 简短 提示 。 协 管 员 既 能 看 到 这 个 提 


示 ， 也 能 看 到 评论 的 正文 。 在 每 篇 评论 的 下 方 ， 协 管 员 还 能 看 到 一 个 按钮 ， 用 来 切换 订 





Fi 论 


的 状态 。 点 击 按钮 后 会 触发 两 个 新 路 由 中 的 一 个 ， 但 具体 触发 哪 一 个 取决 于 协 管 员 要 把 评 


论 设 为 什么 状态 。 这 两 个 新 路 由 的 定义 如 示例 13-10 所 示 。 
示例 13-10 app/main/views.py: 评论 管理 路 由 


@main.route('/moderate/enable/<int:id>') 
@login_required 
@permission_required(Permission .MODERATE) 
def moderate_ enable(id): 
Comment = Comment.query.get_or_404(id) 
Comment .disabLed = False 
db.session.add(comment) 
return redirect(url_for('.moderate', 
page=request.args.get('page', 1, type=int))) 


@main.route('/moderate/disable/<int:id>') 





@login_required 
@permission_required(Permission.MODERATE) 
def moderate_disable(id): 
Comment = Comment.query.get_or_404(id) 
comment.disabled = True 
db.session.add(comment) 
return redirect(url_ for(' .moderate ' ， 
page=request.args.get('page', 1, type=int))) 


上 述 启 用 路 由 和 禁用 路 由 先 加 载 评论 对 象 ， 把 dtsabtLed 字段 设 为 恰当 的 值 ， 再 把 评论 对 象 
写 入 数据 库 。 最 后 ， 重 定向 到 评论 管理 页 面 (如 图 13-3 所 示 )， 如 果 查 询 字符 串 中 指定 了 
page 参数 ， 会 将 其 传人 重 定 向 操作 。_comments.html 模板 中 的 按钮 指定 了 page 参数 ， 重 
定向 后 会 返回 之 前 的 页 面 。 














@OO Flasky - Comment Moderation 


AI) 从 || + | localhost:5000 









Comment Moderation 












马 时 john a minute ago 
vr Thank you! 


miguel 2 minutes ago 
Congratulations! This is a great article! 


ED 
aday ago 


国 miguel 
This comment has been disabled by a moderator. 





Thank you! 


Enable 











图 13-3: 评论 管理 页 面 


如 果 你 从 GitHub 上 克隆 了 这 个 应 用 的 Git 仓库 ， 那 么 可 以 执行 git checkout 
13b 检 出 应 用 的 这 个 版 本 。 





对 社交 功能 的 介绍 到 此 结束 。 下 一 章 将 讨论 如 何以 API 的 形式 开放 应 用 的 功能 ， 供 智能 手 
机 应 用 等 客户 端 使 用 。 
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第 14 章 


应 用 编程 接口 





近 些 年 ，Web 应 用 有 种 趋势 ， 那 就 是 业务 逻辑 被 越 来 越 多 地 移 到 客户 端 ， 开 创 出 了 一 种 称 
为 富 互 联网 应 用 (RIA，trich Internet application) 的 架构 。 在 RIA 中 ， 服 务 器 的 主要 功能 
(有 时 是 唯一 功能 ) 是 为 客户 端 提供 数据 存 取 服务 。 在 这 种 模式 中 ， 服 务 器 变 成 了 Web 服 
务 或 应 用 编程 接口 (API，application programming interface)。 

RIA 可 采用 多 种 协议 与 Web 服务 通信 。 远 程 过 程 调用 (RPC，remote procedure call) 协议 , 例 
如 XML-RPC, 以 及 由 其 衍生 的 简单 对 象 访问 协议 (SOAP，simplified object access protocol) ， 
在 几 年 前 比较 受 欢 迎 。 最 近 ， 表 现 层 状态 转移 (REST，representational state transfer) 架构 
轿 露 头角 ， 成 为 Web 应 用 的 新 宠 ， 因 为 这 种 架构 建立 在 大 家 熟识 的 万 维 网 基础 之 上 。 
Flask 是 开发 REST 架构 Web 服务 的 理想 框架 ， 因 为 Flask 天 生 轻 量 。 在 本 章 ， 你 将 学 到 
如 何 使 用 Flask 实现 符合 REST 架构 的 API。 


14.1 REST 简 介 


Roy Fielding 在 其 博士 论文 “Architectural Styles and the Design of Network-based Software 
Architectures” 的 第 5 章 中 描述 了 Web 服务 的 REST 架构 方式 ， 并 列 出 了 6 个 符合 这 一 架 
构 定义 的 特征 。 
客户 端 - 服务 器 
客户 端 和 服务 器 之 间 必 须 有 明确 的 界线 。 
无 状态 
客户 端 发 出 的 请 求 中 必须 包含 所 有 必要 的 信息 。 服 务 器 不 能 在 两 次 请 求 之 间 保 存 客户 端 
的 任何 状态 。 
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缓存 
服务 器 发 出 的 响应 可 以 标记 为 可 缓存 或 不 可 缓存 ， 这 样 出 于 优化 目的 ， 客 户 端 (或 客户 
端 和 服务 器 之 间 的 中 间 服 务 ) 可 以 使 用 缓存 。 

接口 统一 
客户 端 访问 服务 器 资源 时 使 用 的 协议 必须 一 致 、 定 义 良好 ， 且 已 经 标准 化 。 这 是 REST 
架构 最 复杂 的 一 方面 ， 涉 及 唯一 的 资源 标识 符 、 资 源 表 述 、 客 户 端 和 服务 器 之 间 自 描述 
的 消息 ， 以 及 超 媒 体 (hypermedia)。 

系统 分 层 


在 客户 端 和 服务 器 之 间 可 以 按 需 插入 代理 服务 器 、 缓 存 或 网 关 ， 以 提高 性 能 、 稳 定性 和 
伸缩 性 。 


按 需 编程 
客户 端 可 以 选择 从 服务 器 中 下 载 代 码 ， 在 客户 端的 上 下 文中 执行 。 



































14.1.1 资源 就 是 一 切 

资源 是 REST 架构 风格 的 核心 概念 。 在 REST 架构 中 ， 资 源 是 应 用 中 你 要 着 重 关 注 的 事物 。 
例如 ， 在 博客 应 用 中 ， 用 户 、 博 客 文 章 和 评论 都 是 资源 。 

每 个 资源 都 要 使 用 唯一 的 URL 表示 。 对 HTTP 协议 来 说 ， 资 源 的 标识 符 是 URL。 还 是 以 
博客 应 用 为 例 ， 一 篇 博客 文章 可 以 使 用 URL /api/posts/12345 表示 ， 其 中 12345 是 这 篇 文章 
的 唯一 标识 符 ， 使 用 文章 在 数据 库 中 的 主键 表示 。URL 的 格式 或 内 容 无 关 紧 要 ， 只 要 资源 
的 URL 只 表示 唯一 的 一 个 资源 即 可 。 

某 一 类 资源 的 集合 也 要 有 一 个 URL。 博 客 文 章 集合 的 URL 可 以 是 /api/posts/， 评 论 集 合 的 
URL 可 以 是 /api/comments/。 

API 还 可 以 为 某 一 类 资源 的 逻辑 子 集 定义 集合 URL。 例 如 ， 编 号 为 12345 的 博客 文章 ， 其 
中 的 所 有 评论 可 以 使 用 URL /api/posts/12345/comments/ 表示 。 表 示 资 源 集 合 的 URL 习惯 
在 末端 加 上 一 个 斜 线 ， 代 表 一 种 “ 子 目 录 ” 结 构 。 


注意 ，Flask 会 特殊 对 竺 末端 带 有 和 斜 线 的 路 由 。 如 果 客 户 端 请 求 的 URL 的 末 
端 没 有 和 斜 线 ， 而 唯一 匹配 的 路 由 末端 有 和 斜 线 ，Flask 会 自动 响应 一 个 重 定向 ， 
转向 末端 带 斜 线 的 URL。 反 之 则 不 会 重 定向 。 






































14.1.2 请求 方法 

客户 端 应 用 在 建立 起 的 资源 URL 上 发 送 请 求 ， 使 用 请 求 方法 表示 期 望 的 操作 。 若 要 从 博 
客 API 中 获取 博客 文章 列表 ， 客 户 端 可 以 向 http://www.example.com/api/posts/ 发 送 GET 请 
求 。 若 要 插入 一 篇 新 博客 文章 ， 客 户 端 可 以 向 同一 地 址 发 送 P05T 请 求 ， 而 且 请 求 主体 中 
要 包含 博客 文章 的 内 容 。 若 要 获取 编号 为 12345 的 博客 文章 ， 客 户 端 可 以 向 http://www. 
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example.com/api/posts/12345 发 送 GET 请 求 。 表 14-1 列 出 了 REST 式 API 中 常用 的 请 求 方 
法 及 其 含义 。 
表 14-1: REST 式 API 使 用 的 HTTP 请 求 方法 







































































请 求 方法 目 标 说 明 HTTP 状 态 码 
GET 单个 资源 的 URL ”获取 目标 资源 200 
GET 资源 集合 的 URL ”获取 资源 的 集合 (如果 服 务 器 实现 了 分 页 ， 还 可 以 是 一 200 
页 中 的 资源 ) 
POST 资源 集合 的 URL ”创建 新 资源 ， 并 将 其 加 入 目标 集合 。 服 务 器 为 新 资源 指 201 
派 URL， 并 在 响应 的 Location 首部 中 返 匠 
PUT 单个 资源 的 URL ”修改 一 个 现 有 资源 。 如 果 客 户 端 能 为 资源 指派 URL， 还 200 或 204 
可 用 来 创建 新 资源 
DELETE 单个 资源 的 URL I 除 一 个 资源 200 或 204 
DELETE 资源 集合 的 URL I 除 目 标 集合 中 的 所 有 资源 200 或 204 








REST 架构 不 要 求 必 须 为 一 个 资源 实现 所 有 的 请 求 方法 。 如 果 资 源 不 支持 客 
户 端 使 用 的 请 求 方法 ， 响 应 的 状态 码 为 405 (不 允许 使 用 的 方法 )。Flask 会 
自动 处 理 这 种 错误 。 








请 求 方 法 不 止 GET、POST、PUT 和 DELETE。HTTP 协议 还 定义 了 其 他 方法 ， 例 如 HEAD 和 
OPTIONS， 这 些 方 法 由 Flask 自动 实现 。 


14.1.3 请求 和 响应 主体 


在 请 求 和 响应 的 主体 中 ， 资 源 在 客户 端 和 服务 器 之 间 来 回 传送 ， 但 REST 没有 指定 编码 
资源 的 方式 。 请 求 和 响应 中 的 Content-Type 首部 用 于 指明 主体 中 资源 的 编码 方式 。 使 用 
HTTP 协议 的 内 容 协商 机 制 ， 可 以 找到 一 种 客户 端 和 服务 器 都 支持 的 编码 方式 。 

REST 式 Web 服务 常用 的 两 种 编码 方式 是 JavaScript 对 象 表示 法 (JSON，JavaScript object 
notation) 和 可 扩展 标记 语言 (XML，extensible markup language)。 对 基于 Web 的 RIA 来 
说 ，JSON 更 具 吸 引力 ， 因 为 JSON 比 XML 简洁 ， 而 且 JSON 与 Web 浏览 器 使 用 的 客户 
端 脚本 语言 JavaScript 联系 紧密 。 继 续 以 博客 API 为 例 ， 一 篇 博客 文章 对 应 的 资源 可 以 使 
用 如 下 的 JSON 表示 : 











"self_url": "http://www.example.com/api/posts/12345", 

"title": "Writing RESTfUL APIs in Python", 

"author_url": "http://www.example.com/api/users/2", 

"body": "... text of the article here ...", 

"comments_url": "http://www.example.com/api/posts/12345/comments" 
} 


注意 ，seLf_urL、author_urt 和 comments_url 字段 都 是 完整 的 资源 URL。 这 是 很 重要 的 表 
示 方 法 ， 因 为 客户 端 可 以 通过 这 些 URL 发 掘 新 资源 。 





























在 设计 良好 的 REST 式 API 中 ， 客 户 端 只 需 知 道 儿 个 顶级 资源 的 URL， 其 他 资源 的 URL 
则 从 响应 中 包含 的 链接 上 发 据 。 这 就 好 比 浏览 网 络 时 ， 你 在 自己 知道 的 网 页 中 点 击 链接 发 
掘 新 网 页 一 样 。 


14.1.4 版 本 

在 传统 的 以 服务 器 为 中 心 的 Web 应 用 中 ， 服 务 器 完全 掌控 应 用 。 更 新 应 用 时 ， 只 需 在 服务 
器 上 部 署 新 版 本 就 可 更 新 所 有 的 用 户 ， 因 为 运行 在 用 户 Web 浏览 器 中 的 那 部 分 应 用 也 是 从 
服务 器 上 下 载 的 。 

但 升级 RIA 和 Web 服务 要 复杂 得 多 ， 因 为 客户 端 应 用 和 服务 器 上 的 应 用 是 相互 独立 的 ， 
有 时 甚至 由 不 同 的 人 开发 。 你 可 以 考虑 一 下 这 种 情况 ， 即 一 个 应 用 的 REST 式 Web 服务 被 
很 多 客户 端 使 用 ， 其 中 包括 Web 浏览 器 和 智能 手机 原生 应 用 。 服 务 器 可 以 随时 更 新 Web 
浏览 器 中 的 客户 端 ， 但 无 法 强制 更 新 智能 手机 中 的 应 用 ， 因 为 更 新 前 先 要 获得 机 主 的 许 
可 。 即 便 机 主 想 更 新 ， 也 不 能 保证 每 个 智能 手机 都 更 新 到 服务 器 端 部 署 的 新 版 本 了 。 


基于 以 上 原因 ，Web 服务 的 容错 能 力 要 比 一 般 的 Web 应 用 强 ， 而 且 还 要 保证 旧版 客户 端 
能 继续 使 用 。 更 新 Web 服务 一 定 要 格外 小 心 ， 倘 若 破 坏 了 向 后 兼容 性 ， 如 果 客 户 端 没有 更 
新 到 新 版 ， 现 有 的 客户 端 将 无 法 使 用 。 这 一 问题 的 常见 解决 办 法 是 使 用 版 本 区 分 Web 服务 
所 处 理 的 URL。 例 如 ， 首 次 发 布 的 博客 Web 服务 可 以 通过 /api/v1/posts/ 提供 博客 文章 的 
集合 。 

在 URL 中 加 入 Web 服务 的 版 本 号 有 助 于 组 织 化 管理 新 旧 功 能 ， 让 服务 器 能 为 新 客户 端 提 
供 新 功能 ， 同 时 继续 支持 旧版 客户 端 。 博 客服 务 可 能 会 修改 博客 文章 使 用 的 JSON 格式 ， 
通过 /api/v2/posts/ 提供 修改 后 的 博客 文章 ， 而 客户 端 仍 能 通过 /api/v1/posts/ 获取 旧 的 JSON 
格式 。 

提供 多 版 本 支持 会 增加 服务 器 的 维护 负担 ， 但 在 某 些 情况 下 ， 这 是 不 破坏 现 有 部 署 且 能 让 
应 用 不 断 发 展 的 唯一 方式 。 等 到 所 有 客户 端 都 升级 到 新 版 之 后 ， 可 以 弃 用 旧版 服务 ， 待 时 
机 成 熟 后 再 把 旧版 完全 删除 。 


14.2 ”使 用 Flask 实 现 REST 式 Web 服 务 


使 用 Flask 创建 REST 式 Web 服务 十 分 简单 。 使 用 熟悉 的 route() 装饰 器 及 其 methods 可 
选 参数 可 以 声明 服务 所 提供 资源 URL 的 路 由 。 处 理 JSON 数据 同样 简单 ， 请 求 中 的 JSON 
数据 可 以 通过 request.get_json() 转换 成 字典 格式 ， 而 且 可 以 使 用 Flask 提供 的 辅助 函数 
jsonify()， 从 Python 字典 中 生成 需要 包含 JSON 的 响应 。 


以 下 几 节 介绍 如 何 扩展 Flasky， 增 加 一 个 REST 式 Web 服务 ， 让 客户 端 访问 博客 文章 及 相 
关 资 源 。 













































































14.2.1 创建 API 蓝 本 


REST 式 API 相关 的 路 由 是 应 用 中 一 个 自 成 一 体 的 子 集 。 因 此 ， 为 了 更 好 地 组 织 代码 ， 最 
好 把 这 些 路 由 放 到 独立 的 蓝本 中 。 这 个 API 蓝本 的 基本 结构 如 示例 14-1 所 示 。 
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示例 14-1 API 蓝本 的 结构 
| -fLasky 
| -app/ 
| -api 
|-_init .py 
-Users.py 
-posts.py 
-Comments.py 
-authentication.py 
-errors.py 
-decorators.py 


如 有 果 以 后 需要 创建 一 个 向 前 兼容 的 API 版 本 ， 可 以 再 添加 一 个 带 版 本 号 的 包 ， 让 应 用 同时 
支持 两 个 版 本 的 API。 
在 这 个 API 蓝本 中 ， 各 资源 分 别 在 不 同 的 模块 中 实现 。 蓝 本 中 还 包含 处 理 身 份 验 证 、 错 误 
以 及 提供 自 定义 装饰 器 的 模块 。 蓝 本 的 构造 文件 如 示例 14-2 所 示 。 


示例 14-2 app/api/_init .py: API 蓝本 的 构造 文件 
from flask import Blueprint 























api = Blueprint('api', _ name ) 


from . import authentication, posts, users, comments, errors 


这 个 监 本 的 包 构 造 文件 与 其 他 蓝本 的 类 似 。 一 定 要 导入 监 本 中 的 所 有 模块 ， 这 样 才能 注册 
路 由 和 错误 处 理 程序 。 因 为 很 多 模块 要 导入 api 包 ， 所 以 相关 模块 在 底部 导入 ， 以 防 循环 
依赖 导致 出 错 。 


注册 API 蓝本 的 代码 如 示例 14-3 所 示 。 


示例 14-3 app/_init .py: 注册 API 蓝本 
def create_app(config name): 
Hs 
from .api import api as api_blueprint 
app.register_blueprint(api_blueprint, url_prefix='/api/v1') 
i 


























注册 API 蓝本 时 指定 了 一 个 URL 前 级 ， 因 此 蓝本 中 所 有 路 由 的 URL 都 将 以 /api/v1 开头 。 
注册 蓝本 时 设置 前 级 是 个 好 主意 ， 这 样 就 无 须 在 蓝本 的 每 个 路 由 中 硬 编码 版 本 号 了 。 


14.2.2 ”错误 处 理 


REST 式 Web 服务 将 请 求 的 状态 告知 客户 端 时 ， 会 在 响应 中 发 送 适当 的 HTTP 状态 码 ， 并 
将 额外 信息 放 入 响应 主体 。 客 户 端 从 Web 服务 得 到 的 常见 状态 码 如 表 14-2 所 示 。 


表 14-2: API 返 回 的 常见 HTTP 状 态 码 

















HTTP 状 态 码 名 称 说 明 
200 OK (成 功 ) 请 求 成 功 
201 Created (已 创建 ) 请 求 成 功 ， 而 且 创 建 了 一 个 新 资源 
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( 续 ) 



































HTTP 状 态 码 名 称 说 明 

202 Accepted (已 接收 ) 请 求 已 接收 ， 但 仍 在 处 理 中 ， 将 异 
步 处 理 

204 No Content (没有 内 容 ) 请 求 成 功 处 理 ， 但 是 返回 的 响应 没 
有 数据 

400 Bad Request ( 坏 请 求 ) 请 求 无 效 或 不 一 致 

401 Unauthorized (未 授权 ) 请 求 未 包含 身份 验证 信息 ， 或 者 提 
供 的 凭据 无 效 

403 Forbidden (禁止 ) 请 求 中 发 送 的 身份 验证 凭据 无 权 访 
问 目标 

404 Not Found (未 找到 ) URL 对 应 的 资源 不 存在 

405 Method Not Allowed (不 允许 使 用 的 方法 ) 指定 资源 不 支持 请 求 使 用 的 方法 

500 Internal Server Error (内 部 服务 器 错误 ) 处 理 请 求 的 过 程 中 发 生意 外 错误 




















处 理 404 和 500 状态 码 时 会 遇 到 点 小 麻烦 ， 因 为 这 两 个 错误 是 由 Flask 自己 生成 的 ， 而且 
一 般 会 返回 HTML 响应 。 这 很 可 能 会 让 API 客户 端 困 惑 ， 因 为 客户 端 期 望 所 有 响应 都 是 
JSON 格式 。 


为 所 有 客户 端 生成 适当 响应 的 一 种 方法 是 ， 在 错误 处 理 程 序 中 根据 客户 端 请 求 的 格式 改写 
响应 ， 这 种 技术 称 为 内 容 协 商 。 示 例 14-4 是 改进 后 的 404 错误 处 理 程序 ， 它 向 Web 服务 
客户 端 发 送 JSON 格式 响应 ， 除 此 之 外 则 发 送 HTML 格式 响应 。500 错误 处 理 程序 的 写法 
类 似 。 


示例 14-4 app/api/errors.py: 使 用 HTTP 内 容 协 商机 制 处 理 404 错误 
@main.app_errorhandler(404) 
def page_not_ found(e): 
if request.accept mimetypes.accept_json and \ 
not request.accept_ mimetypes.accept_html: 
response = jsonify({'error': 'not found'}) 
response.status_code = 404 
return response 
return render_template('404.html'), 404 


这 个 新 版 错误 处 理 程序 检查 Accept 请 求 首部 (解码 为 request.accept_mimetypes)， 根 据 
首部 的 值 决 定 客户 端 期 望 接收 的 响应 格式 。 浏 览 器 一 般 不 限制 响应 的 格式 ， 但 是 API 客 
户 端 通常 会 指定 。 仅 当 客 户 端 接受 的 格式 列表 中 包含 JSON 但 不 包含 HTML 时 ， 才 生成 
JSON 响应 。 

其 他 状态 码 都 由 Web 服务 生成 ， 因 此 可 在 蓝本 的 errors.py 模块 中 以 辅助 函数 的 形式 实现 。 
示例 14-5 是 403 错误 的 处 理 程序 ， 其 他 错误 处 理 程序 的 实现 方式 与 此 类 似 。 


示例 14-5 ”app/api/errors.py: API 蓝本 中 403 状态 码 的 错误 处 理 程序 
def forbidden(message): 
response = jsonify({'error': 'forbidden', 'message': message}) 
response.status_code = 403 
return response 






















































































API 蓝本 中 的 视图 函数 在 必要 时 可 以 调用 这 些 辅助 函数 生成 错误 响应 。 


14.2.3 ”使 用 Flask-HTTPAuth 验 证 用 户 身份 

与 普通 Web 应 用 一 样 ，Web 服务 也 需要 保护 信息 ， 确 保 未 经 授权 的 用 户 无 法 访问 。 为 此 ， 
RIA 必须 询问 用 户 的 登录 凭据 ， 并 将 其 传 给 服务 器 进行 验证 。 

前 面 说 过 ，REST 式 Web 服务 的 特征 之 一 是 无 状态 ， 即 服务 器 在 两 次 请 求 之 间 不 能 “ 记 
住 ” 客 户 端的 任何 信息 。 客 户 端 必须 在 发 出 的 请 求 中 包含 所 有 必要 信息 ， 因 此 所 有 请 求 都 
必须 包含 用 户 凭据。 

Flasky 应 用 当前 的 登录 功能 是 在 Flask-Login 的 帮助 下 实现 的 ， 数 据 存储 在 用 户 会 话 中 。 默 
认 情 况 下 ，Flask 把 会 话 保存 在 客户 端 cookie 中 ， 因 此 服务 器 没有 保存 任何 用 户 相关 信息 ， 
都 转交 给 客户 端 保存 。 这 种 实现 方式 看 起 来 遵守 了 REST 架构 的 无 状态 要 求 ， 但 在 REST 
式 Web 服务 中 使 用 cookie 有 点 不 现实 ， 因 为 Web 浏览 器 之 外 的 客户 端 很 难 提供 对 cookie 
的 支持 。 鉴 于 此 ， 在 API 中 使 用 cookie 并 不 是 一 个 很 好 的 设计 选择 。 


REST 架构 的 无 状态 要 求 看 起 来 似乎 过 于 严格 ， 但 这 并 不 是 随意 提出 的 要 
求 一 一 无 状态 的 服务 器 伸缩 起 来 更 加 简单 。 如 果 服 务 器 保存 了 客户 端的 相关 
信息 ， 那 么 必须 保证 特定 客户 端 发 送 的 请 求 由 同一 台 服 务 器 处 理 ， 或 者 使 用 
共享 存储 器 存储 客户 端 数据 。 这 两 点 都 难以 实现 ， 但 是 如 果 服 务 器 是 无 状态 
的 ， 这 两 个 问题 也 就 不 复 存 在 。 















































因为 REST 架构 基于 HTTP 协议 ， 所 以 发 送 凭 据 的 最 佳 方式 是 使 用 HTTP 身份 验证 ， 基 本 
验证 和 摘要 验证 都 可 以 。 在 HITP 身份 验证 中 ， 用 户 赁 据 包 含 在 每 个 请 求 的 Authorization 
首部 中 。 

HTTP 身份 验证 协议 很 简单 ， 可 以 直接 实现 ， 不 过 Flask-HTTPAuth 扩展 提供 了 一 个 便利 的 包 
装 ， 把 协议 的 细节 隐藏 在 装饰 器 之 中 ， 类 似 于 Flask-Login 提供 的 Login_required 装饰 器 。 
Flask-HTTPAuth 使 用 pip 安装 : 





(venv) $ pip install flask-httpauth 


若 想 使 用 HTTP 基本 验证 初始 化 这 个 扩展 ， 要 创建 一 个 HTTPBasicAuth 类 对 象 。 与 Flask- 
Login 一 样 ，Flask-HTTPAuth 不 对 验证 用 户 凭 据 所 需 的 步骤 做 任何 假设 ， 所 需 的 信息 在 回 
调 函 数 中 提供 。 示 例 14-6 展示 了 如 何 初 始 化 Flask-HTTPAuth 扩展 ， 以 及 如 何在 回调 函数 
中 验证 凭据 。 


示例 14-6 app/apiauthentication.py: 初始 化 Flask-HTTPAuth 


from flask_httpauth import HTTPBasicAuth 
auth = HTTPBasicAuth() 

















@auth.verify_password 
def verify_password(email, password): 
if email == "': 
return False 
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User = User.query.filter_by(email = emaiL) .first() 
if not user: 
return False 
g.current_user = User 
return user.verify_password(password) 


因为 这 种 身份 验证 方法 只 在 API 蓝本 中 使 用 ， 所 以 Flask-HTTPAuth 扩展 只 在 蓝本 包 中 初 
始 化 ， 而 不 像 其 他 扩展 那样 要 在 应 用 包 中 初始 化 。 


电子 邮件 和 密码 使 用 User 模型 中 现 有 的 方法 验证 。 如 果 登 录 凭据 正确 ， 这 个 验证 回调 函数 
返回 True， 否 则 返回 False。 如 果 请 求 中 没有 身份 验证 信息 ，Flask-HTTPAuth 也 会 调用 回 
调 函 数 ， 把 两 个 参数 都 设 为 空 字符 串 。 此 时 ，email 的 值 是 一 个 空 字 符 串 ， 回 调 函 数 立即 
返回 False 以 阻 断 请 求 。 某 些 应 用 遇 到 这 种 情况 时 可 以 返回 True， 人 允许 匿名 用 户 访问 。 这 
个 回调 函数 把 通过 身份 验证 的 用 户 保存 在 Flask 的 上 下 文 变量 g 中 ， 供 视图 函数 稍 后 访问 。 


























由 于 每 次 请 求 都 要 传送 用 户 凭据 ，API 路 由 最 好 通过 安全 的 HTTP 对 外 开放 ， 
在 传输 中 加 密 全 部 请 求 和 响应 。 











如 果 身 份 验证 凭据 不 正确 ， 则 服务 器 向 客户 端 返回 401 状态 码 。 默 认 情 况 下 ，Flask- 
HTTPAuth 自动 生成 这 个 状态 码 ， 但 为 了 与 API 返回 的 其 他 错误 保持 一 致 ， 我 们 可 以 自 定 
义 这 个 错误 响应 ， 如 示例 14-7 所 示 。 

示例 14-7 app/api/authentication.py: Flask-HTTPAuth 错误 处 理 程序 


from .errors import unauthorized 








@auth.error_handler 
def auth_ error(): 
return unauthorized('Invalid credentials') 


若 想 保护 路 由 ， 可 使 用 auth.login_required 装饰 器 : 


@api.route('/posts/') 
@auth. login_required 
def get_ posts(): 

pass 


不 过 ， 这 个 蓝本 中 的 所 有 路 由 都 要 使 用 相同 的 方式 进行 保护 ， 所 以 我 们 可 以 在 before_ 
request 处 理 程序 中 使 用 一 次 Login_required 装饰 器 ， 将 其 应 用 到 整个 蓝本 ， 如 示例 14-8 
所 示 。 


示例 14-8 ”app/api/authentication.py: 在 before_request 处 理 程序 中 验证 身份 


from .errors import forbidden 


@api.before_request 
@auth. login_required 
def before_request(): 
if not g.current_user.is anonymous and \ 
not g.current_user.confirmed: 
return forbidden('Unconfirmed account') 




















现在 ，API 蓝本 中 的 所 有 路 由 都 能 自动 验证 身份 。 此 外 ，before_request 处 理 程序 还 会 拒 
绝 已 通过 身份 验证 但 还 没有 确认 账户 的 用 户 。 


14.2.4 ”基于 令 牌 的 身份 验证 

每 次 请 求 ， 客 户 端 都 要 发 送 身 份 验证 凭据 。 为 了 避免 总 是 发 送 敏 感 信 息 (例如 密码 )， 我 
们 可 以 使 用 一 种 基于 令 牌 的 身份 验证 方案 。 

在 基于 令 牌 的 身份 验证 方案 中 ， 客 户 端 先 发 送 一 个 包含 登录 凭据 的 请 求 ， 通 过 身份 验证 
后 ， 得 到 一 个 访问 令 牌 。 这 个 令 牌 可 以 代替 登录 凭据 对 请 求 进行 身份 验证 。 出 于 安全 孝 
虑 ， 令 牌 有 过 期 时 间 。 令 牌 过 期 后 ， 客 户 端 必 须 重 新 发 送 登录 凭据 ， 获 取 新 的 令 牌 。 今 牌 
短暂 的 使 用 期 限 ， 可 以 降低 令 牌 落 入 他 人 之 手 所 导致 的 安全 隐患 。 为 了 生成 和 核查 身份 验 
证 令 牌 ， 我 们 要 在 User 模型 中 定义 两 个 新 方法 。 这 两 个 新 方法 用 到 了 itsdangerous 包 ， 
如 示例 14-9 所 示 。 


示例 14-9 app/models.py: 支持 基于 令 牌 的 身份 验证 


class User(db.Model): 
# 
def generate auth token(self, expiration): 
s = Serializer(current_app.config['SECRET_KEY'], 
expires_in=expiration) 
return s.dumps({'id': self.id}).decode('utf-8') 











@staticmethod 
def verify_auth_token(token): 
s = Serializer(current_app.config['SECRET_KEY']) 
try: 
data = s.loads(token) 
except: 
return None 
return User.query.get(data[ 'id']) 


generate_auth_token() 方法 使 用 编码 后 的 用 户 id 字段 值 生成 一 个 签名 令 牌 ， 还 指定 了 以 秒 
为 单位 的 过 期 时 间 。verify_auth_token() 方法 接受 的 参数 是 一 个 令 牌 ， 如 果 令 牌 有 效 就 返回 
对 应 的 用 户 。verify_auth_token() 是 静态 方法 ， 因 为 只 有 解码 令 牌 后 才能 知道 用 户 是 谁 。 


为 了 能 够 使 用 令 牌 验证 请 求 ， 我 们 必须 修改 Flask-HTTPAuth 提供 的 verify_password 回 
调 ， 除 了 普通 的 凭据 之 外 ， 还 要 接受 令 牌 。 修 改 后 的 回调 如 示例 14-10 所 示 。 


示例 14-10 ”app/api/authentication.py: 改进 核查 回调 ， 支 持 令 牌 


@auth.verify_password 
def verify_password(email_or_token, password): 
if email_or_token == "' 
return False 
if password == "': 
g.current user = User.verify auth token(email_or_token) 
g.token_used = True 
return g.current_user is not None 
user = User.query.filter_by(email=email_or_token).first() 
if not user: 
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return False 
g.current_user = USser 
g.token_used = False 
return user.verify_password(password) 


在 这 个 新 版 本 中 ， 第 一 个 参数 可 以 是 电子 邮件 地 址 ， 也 可 以 是 身份 验证 令 牌 。 如 果 这 个 参 
数 为 空 ， 那 就 和 之 前 一 样 ， 假 定 是 匿名 用 户 。 如 果 密 码 为 空 ， 那 就 假定 email_or_token 参 
数 提供 的 是 令 牌 ， 按 照 令 牌 的 方式 进行 验证 。 如 果 两 个 参数 都 不 为 空 ， 那 么 假定 使 用 常规 
的 邮件 地 址 和 密码 进行 验证 。 在 这 种 实现 方式 中 ， 基 于 令 牌 的 身份 验证 是 可 选 的 ， 由 客户 
端 决定 是 否 使 用 。 为 了 让 视图 函数 能 区 分 这 两 种 身份 验证 方法 ， 我 们 添加 了 g.token_used 
变量 。 

把 身份 验证 令 牌 发 送 给 客户 端的 路 由 也 要 添加 到 API 蓝本 中 ， 具 体 实现 如 示例 14-11 所 示 。 


示例 14-11 app/api/authentication.py: 生成 身份 验证 令 牌 
@api.route('/tokens/', methods=['POST']) 
def get_ token(): 
if g.current_user.is anonymous or g.token_used: 
return unauthorized('Invalid credentials') 
return jsonify({'token': g.current_ user .generate _ auth_ token( 
expiration=3600),'expiration': 3600}) 


因为 这 个 路 由 也 在 蓝本 中 ， 所 以 添加 到 before_request 处 理 程序 上 的 身份 验证 机 制 也 会 用 
在 这 个 路 由 上 。 为 了 确保 这 个 路 由 使 用 电子 邮件 地 址 和 密码 验证 身份 ， 而 不 使 用 之 前 获取 
的 令 牌 ， 我 们 检查 了 g.token_used 的 值 ， 拒 绝 使 用 令 牌 验证 身份 。 这 样 做 是 为 了 防止 用 户 
绕 过 令 牌 过 期 机 制 ， 使 用 旧 令 牌 请 求 新 令 牌 。 这 个 视图 函数 返回 JSON 格式 的 响应 ， 其 中 
包含 过 期 时 间 为 1 小 时 的 令 牌 。 过 期 时 间 也 在 JSON 响应 中 。 


14.2.5 资源 和 JSON 的 序列 化 转换 


开发 Web 服务 时 ， 经 党 需要 在 资源 的 内 部 表示 和 JSON 之 间 进 行 转换 。JSON 是 HITP 请 
求 和 响应 使 用 的 传输 格式 。 把 内 部 表示 转换 成 传输 格式 的 过 程 称 为 序列 化 。 示 例 14-12 是 
新 添加 到 Post 类 中 的 to_json( ) 方法 。 


示例 14-12 ”app/models.py: 把 文章 转换 成 JSON 格式 的 序列 化 字典 


class Post(db.Model): 
Hs 
def to_json(self): 
json_post = { 
'url': url_for('api.get post', id=self.id), 
'body': self.body, 
'body_html': self.body_html, 
'timestamp': self.timestamp, 
'author_url': url_ for('api.get user', id=self.author_id), 
'comments_url': url_for('api.get post_ comments', id=self.id), 
'comment_count': self.comments.count() 
} 


return json_post 
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urL、author_urL 和 comments_url 字段 要 分 别 返回 相应 资源 的 URL， 因 此 它们 的 值 使 用 
url_for() 生成 ， 所 调用 的 路 由 即将 在 API 蓝本 中 定义 。 


这 段 代 码 还 说 明 表 示 资 源 时 可 以 使 用 虚构 的 属性 。comment_count 字段 是 博客 文章 的 评论 
数量 ， 并 不 是 模型 的 真实 属性 ， 它 之 所 以 包含 在 这 个 资源 中 ， 是 为 了 便于 客户 端 使 用 。 


User 模型 的 to_json() 方法 可 以 使 用 类 似 的 方式 实现 ， 如 示例 14-13 所 示 。 
示例 14-13 app/models.py: 把 用 户 转换 成 JSON 格式 的 序列 化 字典 


class User(UserMixin, db.Model): 
# 
def to_json(self): 
json_user = { 
'url': url_for('api.get user', id=self.id), 
'Username': self.usernanme, 
'member_since': self.member_since, 
'last_seen': self.last_seen, 
'posts_url': url_for('api.get user_posts', id=self.id), 
'followed_posts_url': url_for('api.get user_followed posts', 
id=self .id), 

'post_count': self.posts.count() 


























} 
return json_user 
注意 ， 为 了 保护 隐私 ， 人 例如 email 和 role。 这 
段 代码 再 次 说 明 ， 提 供给 客户 端的 资源 表示 没 必 要 与 数据 库 模 型 的 内 部 定义 完全 一 致 。 
序列 化 的 逆向 操作 称 为 反 序列 化 。 把 JSON 结构 反 序 列 化 成 模型 时 面临 的 问题 是 ， 客 户 端 
提供 的 数据 可 能 无 效 、 错 误 或 者 多 余 。 示 例 14-14 是 从 JSON 格式 数据 创建 Post 模型 实例 
的 方法 。 


示例 14-14 app/models.py: 从 JSON 格式 数据 创建 一 篇 博客 文章 


from app.exceptions import ValidationError 





class Post(db.Model): 

Ce 

@staticmethod 

def from json(json_post): 
body = json_post.get('body' 
if body is None or body == ' ': 

raise ValidationError('post does not have a body ' ) 

return Post(body=body) 


如 你 所 见 ， 上 述 代码 在 实现 过 程 中 只 选择 使 用 JSON 字典 中 的 body 属性 ， 忽 略 了 body_ 
html 属性 ， 因 为 只 要 body 属性 的 值 发 生变 化 ， 就 会 触发 一 个 SQLAlchemy 事件 ， 自动 在 
服务 器 端 泻 染 Markdown。 除 非 允 许 客户 端 指定 过 去 或 未 来 的 日 期 (这 个 应 用 并 不 支持 该 
功能 ) ， 否 则 无 须 使 用 timestamp 属性 。 因 为 客户 端 无 权 选 择 博 客 文 章 的 作者 ， 所 以 设 有 使 
用 author_url 字段 。author_url 字段 唯一 能 使 用 的 值 是 通过 身份 验证 的 用 户 。comments_ 
url 和 comment_count 属性 使 用 数据 库 关系 自动 生成 ， 因 此 其 中 没有 创建 文章 所 需 的 有 用 信 
息 。 最 后 ，url 字段 也 被 忽略 了 ， 因 为 在 这 个 实现 中 资源 的 URL 由 服务 器 指派 ， 而 不 是 客 
户 端 。 


-、 
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注意 检查 错误 的 方式 。 如 果 没 有 body 字段 或 者 其 值 为 空 ， 那 么 抛 出 vaLidationError 
异常 。 在 这 种 情况 下 ， 抛 出 异常 才 是 处 理 错误 的 正确 方式 ， 因 为 from_json() 方法 并 
没有 掌握 处 理 问 题 的 足够 信息 ， 唯 有 把 错误 交 给 调用 者 ， 由 上 层 代码 处 理 这 个 错误 。 
ValidationError 类 是 Python 中 ValueError 类 的 简单 子 类 ， 具 体 定义 如 示例 14-15 所 示 。 











示例 14-15 app/exceptions.py: ValidationError 异常 


class ValidationError(ValueError): 
pass 


现在 ， 应 用 需要 处 理 这 个 异常 ， 向 客户 端 提 供 适 当 的 响应 。 为 了 避免 在 视图 函数 中 编写 
捕获 异常 的 代码 ， 可 以 使 用 Flask 的 errorhandter 装饰 器 注册 一 个 全 局 异常 处 理 程序 。 
ValidationError 异常 的 处 理 程序 如 示例 14-16 所 示 。 


示例 14-16 ”app/api/errors.py: API 中 ValidationError 异常 的 处 理 程序 


@api.errorhandler(ValidationError) 
def validation_error(e): 
return bad_request(e.args[0]) 


这 里 使 用 的 errorhandler 装饰 器 与 注册 HTTP 状态 码 处 理 程序 时 使 用 的 是 同一 个 ， 只 不 过 
此 时 接收 的 参数 是 Exception 类 ， 只 要 抛 出 了 指定 类 的 异常 ， 就 会 调用 被 装饰 的 函数 。 注 
意 ， 这 个 装饰 器 从 API 蓝本 中 调用 ， 所 以 只 有 处 理 蓝 本 中 的 路 由 时 抛 出 了 异常 才 会 调用 这 
个 处 理 程序 。 这 样 做 ,视图 函数 中 的 代码 就 可 以 写 得 十 分 简洁 明了 ， 而 且 无 须 检 查 错 误 。 
例如 : 


@api.route('/posts/', methods=['POST']) 
def new_post(): 
post = Post.from json(request.json) 
post.author = g.current_user 
db.session.add(post) 
db.session.commit() 
return jsonify(post.to_json()) 









































14.2.6 ”实现 资源 的 各 个 端点 


接 下 来 我 们 要 实现 处 理 不 同 资源 的 路 由 。GET 请 求 往往 是 最 简单 的 ， 因 为 它们 只 返回 信息 ， 
而 不 做 任何 改动 。 示 例 14-17 是 博客 文章 的 两 个 GET 请 求 处 理 程序 。 


示例 14-17 app/api/posts.py: 文章 资源 GET 请 求 的 处 理 程 
@api.route('/posts/') 
def get_posts(): 
posts = Post.query.all() 
return jsonify({ 'posts': [post.to json() for post in posts] }) 























en 


@api.route('/posts/<int:id>') 

def get _ post(id): 
post = Post.query.get or_404(id) 
return jsonify(post.to_json()) 


第 一 个 路 由 处 理 获 取 文 章 集合 的 请 求 。 这 个 函数 使 用 列表 推导 生成 所 有 文章 的 JSON 版 本 。 
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第 二 个 路 由 返回 单 篇 博客 文章 ， 如 果 在 数据 库 中 没 找到 指定 id 对 应 的 文章 ， 则 返回 404 
错误 。 


博客 文章 资源 的 P05T 请 求 处 理 程序 把 一 篇 新 博客 文章 插入 数据 库 。 路 由 的 定义 如 示例 
14-18 所 示 。 


示例 14-18 app/api/posts.py: 文章 资源 PosT 请 求 的 处 理 程序 


@api.route('/posts/', methods=['POST']) 
@permission_required(Permission.WRITE) 
def new_post(): 

post = Post.from json(request.json) 

post.author = g.current_user 

db.session.add(post) 

db.session.commit() 

return jsonify(post.to_json()), 201, \ 

{'Location': url_for('api.get post', id=post.id)} 


0 个 示例 定义 ) 中 ， 确 保 通过 身份 
2 益 于 前 面 实现 的 错误 处 理 程序 ， 创 建 博 客 文章 的 过 
程 变 PU et a te tn ee 这 个 模 


型 写 人 数据 库 之 后 ， 返 回 201 状态 码 ， 并 把 Location 首部 的 值 设 为 刚 创建 的 这 个 资源 的 
URL。 


注意 ， 为 便于 客户 端 操作 ， 响 应 的 主体 中 包含 了 新 建 的 资源 。 如 此 一 来 ， 客 户 端 就 无 须 在 
创建 资源 后 再 立即 发 起 一 个 GET 请 求 以 获取 资源 。 


用 来 防止 未 授权 用 户 创建 新 博客 文章 的 permission_required 装饰 器 与 应 用 中 使 用 的 类 似 ， 
但 要 针对 API 蓝本 做 些 定制 。 具 体 实现 如 示例 14-19 所 示 。 



























































示例 14-19 ”app/api/decorators.py: permission_required 装饰 器 
def permission_required(permission): 
def decorator(f): 
@wraps(f) 
def decorated function(*args, **kwargs): 
if not g.current user.can(permission): 
return forbidden('Insufficient permissions') 
return f(*args, **kwargs) 
return decorated_ function 
return decorator 


博客 文章 PUT 请 求 的 处 理 程序 用 于 更 新 现 有 资源 ， 如 示例 14-20 所 示 。 


示例 14-20 ”app/api/posts.py: 文章 资源 PUT 请 求 的 处 理 程序 
@api.route('/posts/<int:id>', methods=['PUT']) 
@permission_required(Permission.WRITE) 
def edit post(id): 
post = Post.query.get or_404(id) 
if g.current_ user != post.author and \ 
not g.current_ user.can(Permission.ADMIN): 
return forbidden('Insufficient permissions') 
post.body = request.json.get('body', post.body) 
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db.session.add(post) 
db.session.commit() 
return jsonify(post.to_json()) 


本 例 中 要 进行 的 权限 检查 更 为 复杂 。 检 查 用 户 是 否 有 写 博客 文章 的 权限 通过 装饰 器 实现 ， 
但 为 了 确保 用 户 能 编辑 博客 文章 ， 这 个 函数 还 要 保证 用 户 是 文章 的 作者 或 管理 员 。 此 项 检 
查 直 接 添加 到 视图 函数 中 。 如 果 这 种 检查 要 应 用 于 多 个 视图 函数 ， 为 避免 代码 重复 ， 最 好 
的 做 法 是 定义 装饰 器 。 

因为 应 用 不 允许 删除 文章 ， 所 以 没 必要 实现 DELETE 请 求 方法 的 处 理 程序 。 

用 户 资源 和 评论 资源 的 处 理 程序 实现 方式 类 似 。 表 14-3 列 出 了 这 个 应 用 要 实现 的 资源 ， 以 
及 支持 的 各 个 HTTP 方法 。 完 整 的 实现 参见 本 应 用 的 GitHub 仓库 。 

表 14-3: Flasky 应 用 的 API 资 源 





















































资源 URL 方 法 说 明 

/users/<int:id> GET 返回 一 个 用 户 

/users/<int:id>/posts/ GET 返回 一 个 用 户 发 布 的 所 有 博客 文章 
/users/<int:id>/timeline/ GET 返回 一 个 用 户 所 关注 用 户 发 布 的 所 有 文章 
/posts/ GET 返回 所 有 博客 文章 

/posts/ POST 创建 一 篇 博客 文章 

/posts/<int:id> GET 返回 一 篇 博客 文章 

/posts/<int:id> PUT 修改 一 篇 博客 文章 
/posts/<int:id/>comments/ GET 返回 一 篇 博客 文章 的 评论 
/posts/<int:id/>comments/ POST 在 一 篇 博客 文章 中 添加 一 条 评论 
/comments/ GET 返回 所 有 评论 

/comments/<int:id> GET 返回 一 条 评论 











注意 ， 这 些 资源 只 实现 了 Web 应 用 提供 的 部 分 功能 。 支 持 的 资源 可 以 按 需 扩展 ， 比 如 提供 
关注 者 资源 、 支 持 评论 管理 ， 以 及 API 客户 端 需要 的 其 他 功能 。 


14.2.7 分 页 大 型 资源 集合 


对 大 型 资源 集合 来 说 ， 获 取 集 合 的 GET 请 求 消耗 很 大 ， 而 且 难 以 管理 。 与 Web 应 用 一 样 ， 
Web 服务 也 可 以 对 集合 进行 分 页 。 


示例 14-21 是 分 页 博客 文章 列表 的 一 种 实现 方式 。 


示例 14-21 app/api/posts.py: 分 页 文章 资源 
@api.route('/posts/') 
def get_posts(): 
page = request.args.get('page', 1, type=int) 
pagination = Post.query.paginate( 
page, per_page=current_app.config['FLASKY_POSTS_PER_PAGE'], 
error_out=False) 
posts = pagination.items 
prev = None 
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if pagination.has_prev: 

prev = url_for('api.get posts', page=page-1) 
next = None 
if pagination.has_next: 

next = url_for('api.get posts', page=page+1) 
return jsonify({ 

"posts': [post.to json() for post in posts], 

'prev_url': prev， 

"next_UrL' : next, 

"count ' : pagination.total 


}) 


JSON 格式 响应 中 的 posts 字段 依旧 包含 一 系列 文章 ， 但 现在 这 只 是 其 中 一 页 ， 而 不 是 完 
整 的 集合 。prev_url 和 next_url 字段 分 别 是 前 一 页 和 后 一 页 资源 的 URL， 如 果 某 个 方向 
没有 更 多 分 页 了 ， 则 相应 字段 的 值 为 None。count 是 集合 中 元 素 的 总 数 。 

这 种 技术 可 应 用 于 所 有 返回 集合 的 路 由 。 


如 果 你 从 GitHub 上 克隆 了 这 个 应 用 的 Git 仓库 ， 那 么 可 以 执行 git checkout 
14a 检 出 应 用 的 这 个 版 本 。 为 保证 安装 了 所 有 依赖 ， 还 要 执行 ptp install 


-rr _ requirements/dev.txt。 











14.2.8 使 用 HTTPie 测 试 Web 服 务 


测试 Web 服务 必须 使 用 HTTP 客户 端 。 在 命令 行 中 测试 Web 服务 最 常 使 用 的 两 个 客户 端 
是 cURL 和 HTTPie。 这 两 个 工具 都 很 强大 ， 但 后 者 的 命令 行 句 法 更 简洁 ， 可 读 性 也 更 高 ， 
而 且 为 API 请 求 做 了 特别 优化 。HTTPie 使 用 pip 安装 : 


(venv) $ pip install httpie 


假设 开发 服务 器 运行 在 默认 地 址 http:/127.0.0.1:5000 上 。 在 另 一 个 终端 窗口 中 ， 可 按照 如 
下 的 方式 发 起 GET 请 求 : 


(venv) $ http --json --auth <email>:<password> GET \ 
> http://127.0.0.1:5000/api/v1/posts 

HTTP/1.0 200 OK 

Content-Length: 7018 

Content-Type: application/json 

Date: Sun, 22 Dec 2013 08:11:24 GMT 

Server: Werkzeug/0.9.4 Python/2.7.3 





{ 
"posts" [ 
]， 
"prev_url": null 
"next_url": "http://127.0.0.1:5000/api/vi/posts/?page=2", 
"count": 150 
} 








注意 响应 中 的 分 页 链接 。 因 为 这 是 第 一 页 ， 所 以 没有 上 一 页 ， 不 过 返回 了 获取 下 一 页 的 





URL 和 总 数 。 
下 面 这 个 命令 发 送 PoST 请 求 ， 添 加 一 篇 新 博客 文章 : 














(venv) $ http --auth <email>:<password> --json POST \ 
> http://127.0.0.1:5000/api/vi/posts/ \ 

> "body=I'm adding a post from the *command line*." 
HTTP/1.0 201 CREATED 

Content-Length: 360 

Content-Type: application/json 

Date: Sun, 22 Dec 2013 08:30:27 GMT 

Location: http://127.0.0.1:5000/api/v1i/posts/111 
Server: Werkzeug/0.9.4 Python/2.7.3 


{ 
"author": "http://127.0.0.1:5000/api/vi/users/1", 


"body": "I'm adding a post from the *command line*.", 





"body_html": "<p>I'm adding a post from the <em>command line</em>.</p>", 
"comments": "http://127.0.0.1:5000/api/v1i/posts/111/comments", 


"comment_count": 0， 

"timestamp": "Sun, 22 Dec 2013 08:30:27 GMT", 

"urL" : "http://127.0.0.1:5000/api/v1i/posts/111" 
} 


如 果 不 想 使 用 用 户 名 和 密码 验证 身份 ， 而 是 使 用 令 牌 ， 要 先 向 /api/v1/tokens/ 发 送 POST 请 求 : 





(venv) $ http --auth <email>:<password> --json POST \ 
> http://127.0.0.1:5000/api/v1/tokens/ 

HTTP/1.0 200 OK 

Content-Length: 162 

Content-Type: application/json 

Date: Sat, 04 Jan 2014 08:38:47 GMT 

Server: Werkzeug/0.9.4 Python/3.3.3 


{ 


"expiration": 3600, 


"token": "eyJpYXQi.0jEzODg4MjQ3MjcsImV4cCI6MTMAODgyODMyNywiYWxnIjoiSFMy..." 


} 





密码 字段 则 留 空 ， 


(venv) $ http --json --auth eyJpYXQ...: GET http://127.0.0.1:5000/api/v1i/posts/ 


令 牌 过 
祝 货 你 ! 第 二 部 分 到 此 结束 。 至 此 ，Flasky 的 功能 开发 阶段 就 完全 结 


期 后 ， 请 求 会 返回 401 错误 ， 指 明 需 要 获取 新 令 牌 。 


在 接 下 来 的 1 小 时 中 ， 可 以 使 用 这 个 令 牌 访问 API。 请 求 时 要 把 用 户 名 字段 设 为 这 个 令 牌 ， 











束 了 。 很 显然 ‘Vy 下 一 


步 要 部 署 应 用 。 在 部 署 过 程 中 ， 我 们 会 遇 到 新 的 挑 成 ， 这 就 是 第 三 部 分 的 主题 。 
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测试 





编写 单元 测试 主要 有 两 个 目的 。 实 现 新 功能 时 ， 单 元 测试 能 够 确保 新 添加 的 代码 按 预期 方 
式 运 行 。 当 然 ， 这 个 过 程 也 可 手动 完成 ， 不 过 自动 化 调试 显然 能 节省 时 间 和 精力 ， 因 为 自 
动 化 测试 能 轻松 地 重复 运行 。 

另外 ， 一 个 更 重要 的 目的 是 ， 每 次 修改 应 用 后 ， 运 行 单元 测试 能 保证 现 有 代码 的 功能 没有 
回归 ， 即 新 改动 没有 影响 原 有 代码 的 正常 运行 。 

从 一 开始 我 们 就 为 Flasky 应 用 编写 了 单元 测试 ， 检 查 数据 库 模 型 类 有 没有 实现 特定 的 功 
能 。 模 型 类 很 容易 在 运行 中 的 应 用 上 下 文 之 外 进行 测试 ， 因 此 不 用 花费 太 多 精力 ， 为 数据 
库 模 型 中 实现 的 全 部 功能 编写 单元 测试 至 少 能 有 效 保证 应 用 的 这 一 部 分 在 不 断 完善 的 过 程 
中 仍 能 按 预期 运行 。 

本 章 将 讨论 如 何 改 进 和 增强 单元 测试 ， 并 覆盖 应 用 的 其 他 部 分 。 


15.1 获取 代码 覆盖 度 报告 


编写 测试 组 件 很 重要 ， 但 知道 测试 的 状况 同样 重要 。 代 码 履 盖 度 工具 用 于 统计 单元 测试 检 
查 了 应 用 的 多 少 功能 ， 并 提供 一 份 详细 的 报告 ， 说 明 应 用 的 哪些 代码 没有 测试 到 。 这 个 信 
息 非常 重要 ， 因 为 它 能 指引 你 为 最 需要 测试 的 部 分 编写 新 测试 。 

Python 提供 了 一 个 优秀 的 代码 覆盖 度 工具 ， 名 为 coverage。 这 个 工具 使 用 pip 安装 : 


(venv) $ pip instaLL coverage 


这 个 工具 本 身 是 一 个 命令 行 脚本 ， 可 在 任何 一 个 Python 应 用 中 检查 代码 覆盖 度 。 除 此 之 
外 ， 它 还 提供 了 更 方便 的 脚本 访问 功能 ， 使 用 编程 方式 启动 覆盖 检查 引擎 。 为 了 能 更 好 地 
把 覆盖 检测 集成 到 第 7 章 添 加 的 flask test 命令 中 ， 我 们 可 以 添加 一 个 --coverage 选项 ， 
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实现 方式 如 示例 15-1 所 示 。 


示例 15-1 flasky.py: 覆盖 度 检 测 
import os 
import sys 
import click 


COV = None 

if os.environ.get('FLASK_COVERAGE'): 
import coverage 
COV = coverage.coverage(branch=True, include='app/*') 
COV.start() 


Hts 


@app.cli.command() 
@click.option('--coverage/--no-coverage', default=False, 
help='Run tests under code coverage.') 
def test(coverage): 
"""Run the unit tests. 
if coverage and not os.environ.get('FLASK_COVERAGE ' ) : 
os .environ['FLASK_COVERAGE'] = '1" 
os.execvp(sys.executable, [sys.executable] + sys.argv) 
import unittest 
tests = unittest.TestLoader().discover('tests') 
unittest.TextTestRunner(verbosity=2).run(tests) 
if COV: 
COV. stop() 
COV.save() 
print('Coverage Summary:') 
COV.report() 
basedir = os.path.abspath(os.path.dirname(__file _)) 
covdir = os.path.join(basedir, 'tmp/coverage') 
COV.html_report(directory=covdir) 
print('HTML version: file://%s/index.html' % covdir) 
COV.erase() 


若 想 查看 代码 覆盖 度 ， 就 把 - -coverage 选项 传 给 flask test 命令 。 为 了 在 test 命令 中 添 
加 这 个 布尔 值 选项 ， 我 们 用 到 了 click.option 装饰 器 。 这 个 装饰 器 把 布尔 值 标志 的 值 作 为 
参数 传 入 函数 。 


不 过 ， 在 flasky.py 脚本 中 集成 代码 覆盖 度 检测 功能 有 个 小 问题 。test() 函数 收 到 
--coverage 选项 的 值 后 再 启动 覆盖 度 检测 为 时 已 晚 ， 那 时 全 局 作用 域 中 的 所 有 代码 都 已 经 
执行 了 。 为 了 保证 检测 的 准确 性 ， 设 定 完 环境 变量 FLASK_COVERAGE 后 ， 脚 本 会 重启 自身 。 
再 次 运行 时 ， 脚 本 顶端 的 代码 发 现 已 经 设 定 了 环境 变量 ， 于 是 立即 启动 覆盖 检测 。 这 一 步 
其 至 发 生 在 导入 全 部 应 用 之 前 。 

coverage.coverage() 国 数 启动 履 盖 度 检 测 引擎 。branch=True 选项 开启 分 支 履 盖 度 分 析 ， 
除了 跟踪 哪 行 代码 已 经 执行 之 外 ， 还 要 检查 每 个 条 件 语 名 的 True 分 支 和 False 分 支 是 否 都 
执行 了 。inctude 选项 限制 检测 的 文件 在 应 用 包 内 ， 因 为 我 们 上 只 需 分 析 这 些 代 码 。 如 果 不 
指定 include 选项 ， 那 么 虚拟 环境 中 安装 的 全 部 扩展 以 及 测试 代码 都 会 包含 于 覆盖 度 报告 



































中 ， 给 报告 添加 很 多 杂项 。 
执行 完 所 有 测试 后 
写 人 磁盘 。 
有 被 覆盖 。 


如 果 你 从 GitHub 上 克隆 了 这 个 应 月 





，test() 国 数 会 在 终端 输 昌 
HTML 格式 以 不 同 的 颜色 注解 全 着 


-rr requirements/dev.txt, 


文本 格式 的 报告 示例 如 下 : 


(venv) $ flask test --coverage 














Ran 23 tests in 6.337s 


OK 
Coverage Summary : 
Name 


app/_init__ .py 
app/api/_ init _ .py 


app/api/authentication.py 


app/api/comments.py 
app/api/decorators.py 
app/api/errors.py 
app/api/posts.py 
app/api/users.py 
app/auth/_ init .py 
app/auth/forms.py 
app/auth/views.py 
app/decorators.py 
app/email.py 
app/exceptions.py 
app/main/_ init_ .py 
app/main/errors.py 
app/main/forms.py 
app/main/views.py 
app/models.py 


TOTAL 
HTML version: 


上 述 报告 口 显示 ， 





872 


整体 覆盖 度 为 45%。 情 况 关 














受 其 他 因素 的 影响 (例如 测试 的 质量 )。 





有 了 这 个 报告 


， 我 们 很 容易 就 能 看 出 ， 为 了 提 


Miss Branch BrPpart Cover 
0 0 0 100% 
0 0 0 100% 

18 10 0 28% 
30 12 0 19% 
3 2 0 62% 
10 0 0 41% 
24 8 0 27% 
24 12 0 14% 
0 0 0 100% 
8 8 0 70% 
91 42 0 16% 
3 2 0 69% 
9 0 0 40% 
0 0 0 100% 
1 0 0 83% 
15 6 0 19% 
7 6 0 71% 
140 34 0 18% 
42 42 6 79% 
425 184 6 45% 


file:///home/flask/flasky/tmp/coverage/index.html 


F 不 遭 ， 但 也 不 太 好 。 现 阶段 ， 模 型 类 是 单元 
测试 的 关注 焦点 ， 在 236 个 语句 中 ， 测 试 覆 盖 了 79%。 很 明显 ，main 和 auth 蓝本 中 的 
views.py 文件 以 及 api 蓝本 中 的 路 由 的 覆盖 度 都 很 低 ， 因 为 我 们 没有 为 这 些 代 码 编写 单元 
测试 。 当 然 ， 这 些 覆 盖 度 指标 无 法 表明 项 目 中 的 代码 是 多 么 健康 ， 因 为 代码 有 设 有 缺陷 还 



































高 覆盖 度 ， 应 该 在 测试 组 们 





报告 ， 同 时 还 会 生成 一 份 HTML 版 本 报告 
了 源码， 标明 哪些 行 被 测试 覆盖 了 ， 而 哪些 没 


的 Git 仓库 ， 那 么 可 以 执行 git checkout 
15a 检 出 应 用 的 这 个 版 本 。 为 保证 安装 了 所 有 依赖 ， 还 要 执行 ptp install 


F 中 添加 哪些 测 


» 
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试 。 但 遗憾 的 是 ， 并 非 应 用 的 所 有 组 成 部 分 都 像 数 据 库 模 型 那样 易于 测试 。 在 接 下 来 的 两 
市 中 ， 我 们 将 介绍 更 高 级 的 测试 策略 ， 可 用 于 测试 视图 函数 、 表 单 和 模板 。 


15.2 Flask 测试 客户 端 


应 用 的 某 些 代码 严重 依赖 运行 中 的 应 用 所 创建 的 环境 。 例 如 ， 你 不 能 直接 调用 视图 国 数 中 
的 代码 进行 测试 ， 因 为 这 个 函数 可 能 需要 访问 Flask 上 下 文 变量 ， 如 request 或 sessilon，; 


视图 





而 言 之 ， 视 图 函数 只 能 在 请 求 上 下 文 和 运行 中 的 应 用 里 运行 。 























函数 可 能 还 等 待 接收 PosT 请 求 中 的 表单 数据 ， 而 且 某 些 视图 函数 要 求 用 户 先 登录 。 简 





Flask 内 建 了 一 个 测试 客户 端 用 于 解决 (至 少 部 分 解决 ) 这 一 问题 。 测 试 客户 端 能 复 现 应 
用 运行 在 web 服务 器 中 的 环境 ， 让 测试 充当 客户 端 来 发 送 请 求 。 

在 测试 客户 端 中 运行 的 视图 函数 和 正常 情况 下 的 没有 太 大 区 别 ， 服 务 器 收 到 请 求 ， 将 其 分 
派 给 合适 的 视图 函数 ， 视 图 函数 生成 响应 ， 将 其 返回 给 测试 客户 端 。 执 行 视图 函数 后 ， 生 
成 的 响应 会 传 入 测试 ， 检 查 是 否 正 确 。 


15.2.1 
示例 15-2 是 一 个 使 用 测试 客户 端 编写 的 单元 测试 框架 。 

示例 15-2 tests/test_client.py: 使 用 Flask 测试 客户 端 编写 的 测试 框架 
import unittest 


from app import create app, db 
from app.models import User, Role 









































测试 Web 应 用 


class FlaskClientTestCase(unittest.TestCase): 


def 


def 


def 


setUp(self): 

self.app = create_app('testing ') 

self.app_context = self.app.app_context() 
self.app_context.push() 

db.create all() 

Role.insert_roles() 

self.client = self.app.test_ client(uyse cookies=True) 


tearDown(self): 
db.session.remove() 
db.drop_all() 
self.app_context.pop() 


test_home_page(seLf ) : 

response = self.client.get('/') 
self.assertEqual(response.status_code, 200) 
self.assertTrue('Stranger' in response.get data(as_text=True)) 


与 tests/test_basics.py 相 比 ， 这 个 模块 添加 了 self.client 实例 变量 ， 它 是 Flask 测试 客户 
端 对 象 。 在 这 个 对 象 上 可 调用 方法 向 应 用 发 起 请 求 。 如 果 创 建 测试 客户 端 时 启用 了 use_ 
cookies 选项 ， 这 个 测试 客户 端 就 能 像 浏 览 器 一 样 接收 和 发 送 cookie， 因 此 能 使 用 依赖 
cookie 的 功能 记 住 请 求 之 间 的 上 下 文 。 值 得 一 提 的 是 ， 启 用 这 个 选项 后 便 可 使 用 存储 在 
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cookie 中 的 用 户 会 话 。 


test_home_page() 测试 是 一 个 简单 的 例子 ， 演 示 了 测试 客户 端的 作用 。 这 里 ， 客 户 端 向 应 
用 的 根 路 由 发 起 了 一 个 请 求 。 在 测试 客户 端 上 调用 get() 方法 得 到 的 结果 是 一 个 Flask 响 
应 对 象 ， 其 内 容 是 调用 视图 函数 得 到 的 响应 。 为 了 检查 测试 是 否 成 功 ， 我 们 先 检 查 响应 的 
状态 码 ， 然 后 通过 response.get_data() 获取 响应 主体 ， 在 里 面 搜索 单词 “Stranger”。 这 个 
词 在 显示 给 匿名 用 户 的 欢迎 消息 中 ， 即 “Hello, Stranger!  。 注 意 ， 默 认 情况 下 get_data() 
返回 的 响应 主体 是 一 个 字 节 数组 ， 传 人 参数 as_text=True 后 得 到 的 是 一 个 更 易于 处 理 的 字 
符 串 。 
测试 客户 端 还 能 使 用 post() 方法 发 送 包 含 表单 数据 的 PosT 请 求 ， 不 过 提交 表单 时 会 有 一 
个 小 麻烦 。 第 4 章 说 过 ，Flask-WTF 生成 的 表单 中 包含 一 个 隐藏 字段 ， 其 内 容 是 CSRF 令 
牌 ， 需 要 和 表单 中 的 数据 一 起 提交 。 为 了 发 送 CSRF 令 牌 ， 测 试 必 须 请 求 表单 所 在 的 页 
面 ， 然 后 解析 响应 返回 的 HTML 代码 ， 从 中 提取 令 牌 ， 这 样 才能 把 令 牌 和 表单 中 的 数据 一 
起 发 送 。 为 了 避免 在 测试 中 处 理 CSRF 令 牌 这 一 烦琐 的 操作 ， 最 好 在 测试 环境 的 配置 中 禁 
用 CSRF 保护 机 制 ， 如 示例 15-3 所 示 。 


示例 15-3 config.py: 在 测试 配置 中 禁用 CSRF 保护 机 制 
class TestingConfig(Config): 
Hs 
WTF_CSRF_ENABLED = False 
示例 15-4 是 一 个 更 为 高 级 的 单元 测试 ， 模 拟 了 新 用 户 注 册 账 户 、 登 录 、 使 用 确认 令 牌 确认 
账户 以 及 退出 等 一 系列 过 程 。 
示例 15-4 ”tests/test_client.py: 使 用 Flask 测试 客户 端 模 拟 新 用 户 注册 的 整个 流程 
class FlaskClientTestCase(unittest.TestCase): 
























































Ha 
def test_ register_and_ login(self): 
# 注册 新 账户 
response = self.client.post('/auth/register', data={ 
'email': 'john@example.com', 
'Username': 'john', 
'password': 'cat', 
'password2': "cat' 
}) 


seLf .assertEquaL(response.status_code，302) 


# 使 用 新 注册 的 账户 登录 
response = self.client.post('/auth/login', data={ 

'email': 'john@example.com', 

'password': 'cat' 
}, follow_redirects=True) 
seLf .assertEquaL(response.status_code，200) 
seLf .assertTrue(re.search('HeLLo,\s+john! ' ， 

response.get data(as_text=True))) 





seLf.assertTrue( 
"You have not confirmed your account yet' in response.get_data( 
as_text=True)) 
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# 发 送 确认 令 牌 
user = User.query.filter_by(email='john@example.com').first() 
token = user.generate confirmation_token() 
response = self.client.get('/auth/confirm/{}'.format(token), 
follow_redirects=True) 
user .confirm(token) 
self.assertEqual(response.status_code, 200) 
seLf .assertTrue( 
'You have confirmed your account' in response.get_data( 
as_text=True)) 


# 退出 


response = self.client.get('/auth/logout', follow_redirects=True) 

self.assertEqual(response.status_code, 200) 

seLf .assertTrue('You have been logged out' in response.get_data( 
as_text=True)) 


这 个 测试 先 向 注册 路 由 提交 一 个 表单 。post() 方法 的 data 参数 是 个 字典 ， 包 含 表单 中 的 
各 个 字段 ， 各 字段 的 名 称 必须 严格 匹配 定义 HTML 表单 时 使 用 的 名 称 。 由 于 CSRF 保护 机 
制 已 经 在 测试 配置 中 禁用 了 ， 因 此 无 须 和 表单 数据 一 起 发 送 。 


/auth/register 路 由 有 两 种 响应 方式 。 如 果 注 册 数 据 可 用 ， 则 返回 一 个 重 定 向 ， 把 用 户 转 到 
登录 页 面 。 示 成功 注册 时 ， 返 回 的 响应 会 再 次 泻 染 注册 表单 ， 而 且 还 包含 适当 的 错误 消 
息 。 为 了 确认 注册 成 功 ， 测 试 检查 响应 的 状态 码 是 否 为 302， 这 个 代码 表示 重 定向 。 


这 个 测试 的 第 二 部 分 使 用 刚才 注册 时 的 电子 邮件 和 密码 登录 应 用 ， 即 向 /auth/login 路 由 发 
起 POST 请 求 。 这 一 次 ， 调 用 post() 方法 时 指定 了 参数 foLtow_redirects=True， 让 测试 客 
户 端 像 浏览 器 那样 ， 自 动向 重 定向 的 URL 发 起 GET 请 求 。 指 定 这 个 参数 后 ， 返 回 的 不 是 
302 状态 码 ， 而 是 请 求 重 定 向 的 URL 返回 的 响应 。 


成 功 登 录 后 的 响应 应 该 是 一 个 页 面 ， 显 示 一 个 包含 用 户 名 的 欢迎 消息 ， 并 提醒 用 户 需 要 确 
认 账 户 才能 获得 权限 。 为 此 ， 我 们 使 用 两 个 断言 语句 检查 响应 是 否 为 这 个 页 面 。 值 得 注意 
的 一 点 是 ， 直 接 搜 索 字 符 串 "HeLtLo， john!' 并 没有 用 ， 因 为 这 个 字符 串 由 动态 部 分 和 静态 
部 分 组 成 ， 而 Jinja2 模板 生成 最 终 的 HTML 时 会 在 二 者 之 间 加 上 额外 的 空格 。 为 了 避免 空 
格 影响 测试 结果 ， 我 们 使 用 正则 表达 式 .。 


下 一 步 要 确认 账户 ， 这 里 也 有 一 个 小 障碍 。 账 户 确认 URL 在 注册 过 程 中 通过 电子 邮件 发 
给 用 户 ， 而 在 测试 中 无 法 轻松 获取 这 个 URL。 上 述 测 试 使 用 的 解决 方法 忽略 了 注册 时 生成 
的 令 牌 ， 直 接 在 User 实例 上 调用 方法 重新 生成 一 个 新 令 牌 。 在 测试 环境 中 ，Flask-Mail 会 
保存 邮件 正文 ， 所 以 还 有 一 种 可 行 的 解决 方法 ， 即 通过 解析 邮件 正文 来 提取 令 牌 。 

得 到 令 牌 后 ， 下 一 步 要 模拟 用 户 点 击 邮件 中 的 确认 URL。 为 此 ， 我 们 要 向 这 个 包含 令 牌 
的 URL 发 起 GET 请 求 。 这 个 请 求 的 响应 是 重 定向 并 转 到 首页 ， 但 这 里 再 次 指定 了 参数 
foLLow_redirects=True， 因 此 测试 客户 端 会 自动 向 重 定向 的 页 面 发 起 请 求 并 返回 响应 。 得 
到 响应 后 ， 检 查 是 否 包含 欢迎 消息 ， 以 及 一 个 向 用 户 说 明确 认 成 功 的 闪现 消息 。 

这 个 测试 的 最 后 一 步 是 向 退出 路 由 发 送 GET 请 求 。 为 了 证 实 成 功 退 出 ， 这 上段 测试 在 响应 中 
搜索 一 个 闪现 消息 。 
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如 果 你 从 GitHub 上 克隆 了 这 个 应 用 的 Git 仓库 ， 那 么 可 以 执行 git checkout 
15b 检 出 应 用 的 这 个 版 本 。 














15.2.2 ”测试 Web 服 务 
Flask 测试 客户 端 还 可 用 于 测试 REST 式 Web 服务 。 示 例 15-5 是 一 个 单元 测试 示例 ， 包 含 
两 个 测试 。 


示例 15-5 ”tests/test_api.py: 使 用 Flask 测试 客户 端 测试 REST 式 API 
class APITestCase(unittest.TestCase): 


# 
def get api_headers(self, username, password): 
return { 
'Authorization': 
'Basic ' + b64encode( 
(username + ':' + password).encode('utf-8')).decode('utf-8'), 
'Accept': 'application/json', 


'Content-Type': "appLication/json' 


} 


def test no_auth(self): 
response = self.client.get(url_for('api.get_ posts'), 
content_type='application/json') 
self.assertEqual(response.status_code, 401) 


def test posts(self): 
# 添加 一 个 用 户 
r = Role.query.filter_by(name='User').first() 
self.assertIsNotNone(r) 
U = User(email='john@example.com', password='cat', confirmed=True, 
role=r) 
db.session.add(u) 
db.session.commit() 














# 写 一 篇 文章 
response = self.client.post( 

'/api/vi/posts/', 
headers=self.get_api_ headers('john@example.com', 'cat'), 
data=json.dumps({'body': 'body of the *blog* post'})) 

self.assertEqual(response.status_code, 201) 

url = response.headers.get('Location') 

self.assertIsNotNone(url) 


# 获取 刚 发 布 的 文章 
response = self.client.get( 
url, 
headers=self .get_api_headers('john@example.com', 'cat')) 
seLf .assertEquaL(response.status_code，200) 
json_response = json.loads(response.get data(as_text=True)) 
seLf .assertEquaL('http://LocaLhost' + json_response[ 'url'], url) 
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self.assertEqual(json_response['body'], 'body of the *blog* post') 
seLf .assertEquaL(json_response[ 'body_htmL ' ] ， 
'<p>body of the <em>blog</em> post</p>') 


测试 API 时 使 用 的 setup() 和 tearDown() 方法 与 测试 普通 应 用 所 用 的 一 样 ， 不 过 API 不 使 
用 cookie， 所 以 无 须 配 置 相 应 支持 。get_api_headers() 是 一 个 辅助 方法 ， 返 回 多 数 API 请 
求 要 发 送 的 通用 首部 ， 包 括 身份 验证 凭据 和 MIME 类 型 相关 的 首部 。 


test_no_auth() 是 一 个 简单 的 测试 ， 确 保 Web 服务 会 拒绝 没有 提供 身份 验证 凭据 的 请 求 ， 
返回 401 错误 码 。test_posts() 测试 把 一 个 用 户 插 入 数据 库 ， 然 后 使 用 基于 REST 的 API 
创建 一 篇 博客 文章 ， 再 读 取 这 篇 文章 。 请 求 主 体 中 发 送 的 数据 要 使 用 json.dumps() 方法 进 
行 编码 ， 因 为 Flask 测试 客户 端 不 会 自动 编码 SON 格式 数据 。 类 似 地 ， 返 回 的 响应 主体 
也 是 JSON 格式 ， 处 理 之 前 必须 使 用 json.loads() 方法 解码 。 
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如 果 你 从 GitHub 上 克隆 了 这 个 应 用 的 Git 仓库 ， 那 么 可 以 执行 git checkout 
15c 检 出 应 用 的 这 个 版 本 。 


15.3 ”使 用 Selenium 进 行 端 到 端 测试 


Flask 测试 客户 端 不 能 完全 模拟 运行 中 的 应 用 所 在 的 环境 。 例 如 ， 如 果 应 用 依赖 在 客户 端 
浏览 器 中 运行 的 JavaScript 代码 的 话 ， 就 不 能 使 用 Flask 测试 客户 端 ， 因 为 返回 给 测试 的 响 
应 中 的 JavaScript 代码 不 会 执行 。 


如 果 测 试 需要 完整 的 环境 ， 除 了 使 用 真正 的 Web 浏览 器 连接 Web 服务 器 中 运行 的 应 用 之 
外 ， 别 无 他 选 。 幸 运 的 是 ， 多 数 Web 浏览 器 都 支持 自动 化 操作 。Selenium 是 一 个 Web 浏 
览 器 自动 化 工具 ， 支 持 3 种 主要 操作 系统 中 的 多 数 主流 Web 浏览 器 

Selenium 的 Python 接口 使 用 pip 安装 : 

(venv) $ pip install selenium 

除了 浏览 器 本 身 ，Selenium 还 要 求 安装 相应 的 驱动 。 主 流 浏览 器 都 有 驱动 ， 如 果 你 想 全 
面 测 试 ， 可 以 编写 一 个 复杂 的 测试 框架 ， 支 持 多 个 浏览 器 。 ww 我 们 只 想 使 用 Google 
Chrome 浏览 器 测试 这 个 应 用 ， 所 以 只 安装 相应 的 驱动 即 可 。 个 驱动 名 为 ChromeDriver， 
如 果 你 使 用 macOS 系统 ， 而 且 计 算 机 中 有 包 安 装 程序 可 以 使 用 下 述 命令 安装 


ChromeDriver: 






























































(venv) $ brew install chromedriver 


如 果 你 使 用 的 是 Linux 或 微软 Windows 系统 ， 抑 或 是 没有 brew 的 macOS 系统 ， 可 以 从 
ChromeDriver 的 网 站 (https://sites.google.com/a/chromium.org/chromedriver/downloads) 下 
载 常规 的 安装 程序 。 

使 用 Selenium 进行 的 测试 要 求 应 用 在 Web 服务 器 中 运行 ， 监 听 真 实 的 HTTP 请 求 。 本 市 
使 用 的 方法 是 ， 让 应 用 运行 在 后 台 线 程 里 的 开发 服务 器 中 ， 而 测试 运行 在 主线 程 中 。 在 测 
试 的 控制 下 ，Selenium 启动 Web 浏览 器 ， 连 接应 用 ， 执 行 所 需 的 操作 。 
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使 用 这 种 方法 要 解决 一 个 问题 ， 即 所 有 测试 都 完成 后 ， 要 停止 Flask 服务 器 ， 
用 一 种 优雅 的 方式 ， 以 便 代 码 覆 盖 度 检测 引擎 等 后 台 作 业 能 够 顺利 完成 。Werkzeug Web 





而 且 最 好 使 


服务 器 本 身 就 有 停止 选项 ， 但 由 于 服务 器 运行 在 单独 的 线程 中 ， 关 闭 服务 器 的 唯一 方法 是 





发 送 一 个 普通 的 HTTP 请 求 。 示 例 15-6 实现 了 关闭 服务 器 的 路 由 。 
示例 15-6 app/main/views.py: 关闭 服务 器 的 路 由 


@main.route('/shutdown') 
def server_shutdown(): 
if not current_app.testing: 
abort(404) 
shutdown = request.environ.get('werkzeug.server.shutdown') 
if not shutdown: 
abort(500) 
shutdown() 
return 'Shutting down...' 














仅 当 应 用 运行 在 测试 环境 中 时 ， 这 个 关闭 服务 器 的 路 由 才 可 用 ;倘若 在 其 他 配置 中 调用 ， 
将 返回 404 响应 。 为 了 关闭 服务 器 ， 我 们 要 调用 Werkzeug 对 环境 开放 的 关闭 函数 。 调 用 














这 个 函数 且 处 理 完 请 求 之 后 ， 开 发 服务 器 就 知道 自己 需要 优雅 地 退出 了 。 
示例 15-7 是 使 用 Selenium 运行 测试 时 ， 测 试用 例 所 用 的 代码 结构 。 


示例 15-7 tests/test_selenium.py: 使 用 Selenium 运行 测试 的 框架 


from selenium import webdriver 





class SeleniumTestCase(unittest.TestCase): 
client = None 


@classmethod 
def setUpClass(cls): 
# 启动 Chrome 
options = webdriver.ChromeOptions() 
options.add_argument('headless') 
try: 
cls.client = webdriver.Chrome(chrome_options=options) 
except: 
pass 


# 如 果 无 法 启动 浏览 器 , 跳 过 这 些 测 试 

if cls.client: 
# 创建 应 用 
cls.app = create app('testing') 
cls.app_context = cls.app.app_context() 
cls.app_context.push() 


# 禁止 日 志 , 保 持 输出 简洁 

import Logging 

Logger = logging.getLogger('werkzeug') 
Logger .setLevel("ERROR") 


# 创建 数据 库 , 并 使 用 一 些 虚拟 数据 填充 
db.create_all() 
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人 台 线 程 终 止 。 随 后 ， 关 闭 浏览 器 ， 删 除 测试 数据 库 。 
. Flask 引入 基于 Click 的 命令 行 界面 之 前 ， 若 想 启动 Flask 的 Web 开发 服务 


Role.insert_roles() 
fake.users(10) 
fake.posts(10) 


# 添加 管理 员 
admin_role = Role.query.filter_by(permissions=Qxff).first() 
admin = User(email='john@example.com', 
username='john', password='cat', 
role=admin_role, confirmed=True) 
db.session.add(admin) 
db.session.commit() 





# 在 一 个 线程 中 启动 FLask 服 务 器 
cls.server_thread = threading.Thread( 
target=cls.app.run, kwargs={'debug': 'false', 
'Use_reloader': False, 
'use_debugger': False}) 
cls.server_thread. start() 


@classmethod 
def tearDownClass(cls): 
if cls.client: 


# 关闭 Flask 服 务 器 和 浏览 器 
cls.client.get('http://Llocalhost:5000/shutdown') 
cls.client.quit() 

cls.server_thread.join() 


# 销毁 数据 库 
db.drop_all() 
db.session.remove() 





# 删除 应 用 上 下 文 
cls.app_context.pop() 





def setUp(self): 
if not self.client: 


self.skipTest('Web browser not available') 


def tearDown(self): 
pass 


setUpClass() 和 tearDownClass() 类 方法 分 别 在 这 个 类 中 的 全 部 测试 运行 之 前 和 之 后 执行 。 
setUpClass() 方法 使 用 Selenium 提供 的 webdriver API 启动 一 个 Chrome 实例 ， 然 后 创建 
一 个 应 用 和 数据 库 ， 在 其 中 写 入 一 些 供 测 试 使 用 的 初始 数据 。 然 后 调用 app.run() 方法 ， 
在 一 个 线程 中 启动 应 用 。 完 成 所 有 测试 后 ， 应 用 会 收 到 一 个 发 往 /shutdown 的 请 求 ， 使 后 














， 要 在 应 用 的 主 脚本 中 调用 app.run() 方法 ， 或 者 使 用 第 三 方 扩 展 ， 例 如 





tin 现在 ， 启 动 服务 器 的 app.run() 方法 被 flask run 命令 代替 了 ， 
不 过 Flask 依然 支持 app.run() 方法 。 这 里 你 便 能 看 到 ， 这 个 方法 在 复杂 的 
测试 情景 中 仍然 有 用 武之 地 。 








除 Chrome 之 外 ，Selenium 还 支持 很 多 Web 浏览 器 。 如 果 你 想 使 用 其 他 Web 
浏览 器 ， 或 者 想 再 额外 测试 别 的 浏览 器 ， 请 查阅 Selenium 文档 (https://docs. 
seleniumhq.org/docs/ )。 




















setUp() 方法 在 每 个 测试 运行 之 前 执行 ， 如 果 Selenium 无 法 利用 startUpClass() 方法 启动 
Web 浏览 器 就 跳 过 测试 。 示 例 15-8 是 一 个 使 用 Selenium 进行 测试 的 例子 。 


示例 15-8 tests/test_selenium.py: Selenium 单元 测试 示例 


class SeleniumTestCase(unittest.TestCase): 
# ... 





def test admin home_page(self): 
# 进入 首页 
self.client.get('http://Llocalhost:5000/') 
self.assertTrue(re.search('Hello,\s+Stranger!', 
self.client.page_source)) 




















# 进入 登录 页 面 
self.client.find element_ by_link text('Log In').click() 
self.assertIn('<h1i>Login</h1i>', self.client.page_source) 


# 登录 

self.client.find _ element_by_name('email').\ 
send_keys('john@example.com') 

self.client.find element_ by_name('password').send keys('cat') 

self.client.find element_ by_name('submit').click() 

self.assertTrue(re.search('Hello,\s+john!', self.client.page_source)) 


# 进入 用 户 资 料 页 面 
self.client.find element_ by_link text('Profile').click() 
seLf .assertIn('<h1>john</h1>' ，seLf.cLient.page_source) 


这 个 测试 使 用 setupctass() 方法 中 创建 的 管理 员 账户 登录 应 用 ， 然 后 打开 用 户 的 资料 页 
面 。 注 意 ， 这 里 使 用 的 测试 方法 与 使 用 Flask 测试 客户 端 时 不 一 样 。 使 用 Selenium 进行 测 
试 时 ， 测 试 向 Web 浏览 器 发 出 指令 ， 从 不 直接 与 应 用 交互 。 发 给 浏览 器 的 指令 与 真实 用 户 
使 用 鼠标 或 键盘 执行 的 操作 几乎 一 样 。 


这 个 测试 首先 调用 get() 方法 访问 应 用 的 首页 。 在 浏览 器 中 ， 这 个 操作 就 是 在 地 址 栏 
中 输入 URL。 为 了 验证 这 一 步 操 作 的 结果 ， 测 试 代码 检查 页 面 源码 中 是 否 包 含 “Hello， 
Stranger!” 这 个 欢迎 消息 。 


为 了 访问 登录 页 面 ， 测 试 使 用 find_element_by_link_text() 方法 查找 “Log In” 链 接 ， 然 
后 在 这 个 链接 上 调用 click() 方法 ， 从 而 在 浏览 器 中 触发 一 次 真正 的 点 击 。Selenium 提供 
了 很 多 find_element_by...() 简便 方法 ， 可 使 用 不 同 的 方式 在 HTML 页 面 中 搜索 元 素 。 


为 了 登录 应 用 ， 测 试 使 用 find_element_by_name() 方法 通过 名 称 找到 表单 中 的 电子 邮件 和 
密码 字段 ， 然 后 再 使 用 send_keys() 方法 在 各 字段 中 填 入 值 。 填 完 之 后 ， 在 提交 按钮 上 调 
用 click() 方 法， 提交 表单 。 然 后 检查 页 面 中 有 没有 针对 用 户 的 欢迎 消息 ， 确 保 登 录 成 功 ， 
而 且 浏 览 器 中 显示 的 是 首页 。 
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测试 的 最 后 一 部 分 在 导航 栏 中 查找 “Profile” 链 接 ， 然 后 点 击 。 为 证 实 资料 页 已 经 加 载 ， 
测试 在 页 面 源码 中 搜索 内 容 为 用 户 名 的 标题 。 
如 果 你 从 GitHub 上 克隆 了 这 个 应 用 的 Git 仓库 ， 那 么 可 以 执行 git checkout 
15d 检 出 应 用 的 这 个 版 本 。 这 次 更 新 包含 一 个 数据 库 迁 移 ， 所 以 签 出 代码 后 
记得 要 执行 flask db upgrade 命令 。 为 保证 安装 了 所 有 依赖 ， 还 要 执行 pip 


install -r requirements/dev.txt, 




















此 时 执行 flask test 命令 ， 你 看 不 到 单元 测试 的 运行 有 什么 差别 。 示 例 15-8 中 的 单 
元 测试 test_admin_home_page 在 无 界面 Chrome 实例 中 运行 ， 并 执行 所 有 操作 。 如 
果 你 想 在 Chrome 窗口 中 查看 执行 的 操作 ， 把 setUpClass() 方 法 中 的 options.add_ 
argument('headless') 一 行 注 释 掉 ， 让 Selenium 启动 带 窗口 的 常规 Chrome 实例 。 


Z 旦 :站 > 二 上 
15.4 值得 测试 吗 
读 到 这 里 你 可 能 会 问 ， 为 了 测试 而 如 此 折腾 Flask 测试 客户 端 和 Selenium， 值 得 吗 ? 这 是 
一 个 合理 的 疑问 ， 但 是 不 容易 回答 。 
不 管 你 是 否 喜 欢 ， 应 用 肯定 要 做 测试 。 如 果 你 自己 不 做 测试 ， 用 户 就 要 充当 不 情愿 的 测试 
员 ， 用 户 发 现 问题 后 ， 你 就 要 顶 着 压力 修正 。 检 查 数据 库 模 型 和 其 他 无 须 在 应 用 上 下 文中 
执行 的 代码 很 简单 ， 而 且 有 针对 性 ， 这 类 测试 一 定 要 做 ， 因 为 你 无 须 投 入 过 多 精力 就 能 保 
证 应 用 逻辑 的 核心 功能 可 以 正常 运行 。 
我 们 有 时 候 也 需要 使 用 Flask 测试 客户 端 和 Selenium 进行 端 到 端 形式 的 测试 ， 不 过 这 类 测 
试 编写 起 来 比较 复杂 ， 只 适用 于 无 法 单独 测试 的 功能 。 应 该 合理 组 织 应 用 代码 ， 尽 量 把 业 
务 逻 辑 写 入 独立 于 应 用 上 下 文 的 模块 中 ， 这 样 测试 起 来 才 更 简单 。 视 图 函数 中 的 代码 应 该 
保持 简洁， 仅 发 挥 粘 合剂 的 作用 ， 收 到 请 求 后 调用 其 他 类 中 相应 的 操作 或 者 封装 应 用 逻辑 
的 函数 。 
因此 ， 测 试 绝对 值得 。 重 要 的 是 我 们 要 设计 一 个 高 效 的 测试 策略 ， 还 要 编写 能 合理 利用 这 
一 策略 的 代码 。 
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第 16 章 
性 能 





没 人 喜欢 运行 缓慢 的 应 用 。 页 面 加 载 时 间 太 长 会 让 用 户 失去 兴趣 ， 所 以 尽早 发 现 并 修正 性 
能 问题 是 一 件 很 重要 的 工作 。 本 章 探讨 调 校 性 能 的 两 个 重要 方法 。 


16.1 在 日 志 中 记录 影响 性 能 的 缓慢 数据 库 查询 


如 果 应 用 的 性 能 随 着 时 间 推移 不 断 降低 ， 很 有 可 能 是 因为 数据 库 查询 变 慢 了 ， 随 着 数据 
库 规模 的 增长 ， 这 一 情况 会 变 得 更 精 。 优 化 数据 库 有 时 很 简单 ， 只 需 添加 更 多 的 索引 即 
可 ， 有 了 时 却 很 复杂 ， 需 要 在 应 用 和 数据 库 之 间 加 入 缓存 。 多 数 数据 库 查 询 语言 都 提供 了 
explain 语句 ， 用 于 显示 数据 库 执行 查询 时 采取 的 步 又 。 从 这 些 步 桑 中， 我 们 经 常 能 发 现 
数据 库 或 索引 设计 的 不 足 之 处 。 

不 过 ， 在 开始 优化 查询 之 前 ， 我 们 必须 知道 哪些 查询 是 值得 优化 的 。 一 次 请 求 往往 可 能 
执行 多 条 数据 库 查询 ， 所 以 经 常 很 难 分 辨 哪 一 条 查询 较 慢 。Flask-SQLAlchemy 提供 了 一 个 
选项 ， 可 以 记录 一 次 请 求 中 与 数据 库 查 询 有 关 的 统计 数据 。 在 示例 16-1 中 可 以 看 到 如 何 使 
用 这 个 功能 把 速度 慢 于 所 设 阔 值 的 查询 写 和 日志 。 


示例 16-1 app/main/views.py: 报告 缓慢 的 数据 库 查询 


from flask_sqlalchemy import get_debug_queries 


















































@main.after_app_request 
def after_request(response): 
for query in get_ debug queries(): 
if query.duration >= current_app.config['FLASKY_SLOW_DB_QUERY_TIME']: 
current_app. logger .warning( 
'Slow query: %s\nparameters: %s\nDuration: %fs\nContext: %s\n' % 
(query.statement, query.parameters, query.duration, 
query.context)) 
return response 
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这 个 功能 使 用 after_app_request 处 理 程序 实现 ， 它 和 before_app_request 处 理 程序 的 工 
作 方 式 类 似 ， 只 不 过 在 视图 函数 处 理 完 请 求 之 后 执行 。Flask 把 响应 对 象 传 给 after_app_ 
request 处 理 程序 ， 以 防 需 要 修改 响应 。 


在 本 例 中 ，after_app_request 处 理 程序 没有 修改 响应 ， 只 是 Flask-SQLAlchemy 记录 
的 查询 时 间 ， 把 缓慢 的 查询 写 入 日 志 (应 用 的 日 志 记 录 器 通过 app.Logger 设置 )， 然 后 再 
返回 响应 ， 发 送 给 客户 端 。 


get_debug_queries() 函数 返回 一 个 列表 ， 其 元 素 是 请 求 中 执行 的 查询 。Flask-SQLAlchemy 
记录 的 查询 信息 如 表 16-1 所 示 。 


表 16-1: Flask-SQLAIchemy 记 录 的 查询 统计 数据 


















































名 称 说 明 

statement SQL 语句 

parameters SQL 语句 使 用 的 参数 

start_time 执行 查询 时 的 时 间 

end_time 返回 查询 结果 时 的 时 间 

duration 查询 持续 的 时 间 ， 单 位 为 秒 

Context 表示 查询 在 源码 中 所 处 位 置 的 字符 串 








这 个 after_app_request 处 理 程 序 遍 历 get_debug_queries() 函数 返回 的 列表 ， 把 持续 时 间 
比 所 设 阔 值 (通过 配置 变量 FLASKY_SLOW_DB_QUERY_TIME 设置 ) 长 的 查询 写 入 日 志 。 这 里 设 
置 的 日 志 等 级 是 “警告 " ， 不 过 有 时 更 适合 把 缓慢 的 数据 库 查 询 视 作 错误 。 


默认 情况 下 ，get_debug_queries() 函数 只 在 调试 模式 中 可 用 。 但 是 数据 库 性 能 问题 很 少 发 生 
在 开发 阶段 ， 因 为 开发 过 程 中 使 用 的 数据 库 较 小 。 因 此 ， 在 生产 环境 中 使 用 该 选项 才 更 能 
挥 它 的 作用 。 若 想 在 生产 环境 中 监控 数据 库 性 能 ， 我 们 必须 修改 配置 ， 如 示例 16-2 所 示 。 


示例 16-2 config.py: 启用 缓慢 查询 记录 功能 的 配置 
class Config: 
Hs 
SQLALCHEMY_RECORD_QUERIES 
FLASKY_SLOW_DB_QUERY_TIME 
# 




















True 
0.5 


SQLALCHEMY_RECORD_QUERIES 告诉 Flask-SQLAlchemy 启用 记录 查询 统计 数据 的 功能 。 我 们 
把 缓慢 查询 的 国 值 设 为 0.5 秒 。 这 两 个 配置 变量 都 在 Config 基 类 中 设置 ， 因此 适用 于 所 有 
环境 。 

每 当 发 现 缓慢 查询 ，Flask 应 用 的 日 志 记 录 器 就 会 写 和 人 一 条 记录 。 若 想 保存 这 些 日 志 记 录 ， 
必须 配置 日 志 记 录 器 。 日 志 记 录 器 的 配置 根据 应 用 所 在 主机 使 用 的 平台 而 有 所 不 同 ， 第 17 
章 会 举 一 些 例子 。 





如 果 你 从 GitHub 上 克隆 了 这 个 应 用 的 Git 仓库 ， 那 么 可 以 执行 git checkout 
16a 检 出 应 用 的 这 个 版 本 。 
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16.2 ”分析 源码 


性 能 问题 的 另 一 个 可 能 诱因 是 高 CPU 消耗 ， 由 执行 大 量 运算 的 国 数 导 致 。 源 码 分 析 器 能 
找 出 应 用 中 执行 最 慢 的 部 分 。 分 析 器 监视 运行 中 的 应 用 ， 记 录 调 用 的 函数 以 及 运行 各 函数 
所 消耗 的 时 间 ， 然 后 生成 一 份 详细 的 报告 ， 指 出 运行 最 慢 的 函数 。 

一 般 只 在 开发 环境 中 分 析 源码 。 源 码 分 析 器 会 导致 应 用 的 运行 速度 比 常规 情 
况 下 慢 得 多 ， 因 为 分 析 器 要 实时 监视 并 记录 应 用 中 发 生 的 一 切 。 不 建议 在 生 
产 环境 中 分 析 源 码 ， 除 非 使 用 专 为 生产 环境 设计 的 轻 量 级 分 析 器 。 





























Flask 使 用 的 Web 开发 服务 器 由 Werkzeug 提供 ， 可 根据 需要 为 每 条 请 求 启用 Python 分 析 
器 。 示 例 16-3 为 应 用 添加 一 个 新 命令 行 选项 ， 在 分 析 器 的 监视 下 启动 Web 服务 器 。 


示例 16-3 flasky.py: 在 请 求 分 析 器 的 监视 下 运行 应 用 
@app.cli.command() 
@click.option('--length', default=25, 
heLp='Number of functions to include ;in the profiler report.') 
@click.option('--profile-dir', default=None, 
heLp='Directory where profiler data files are saved.') 
def profile(length, profile dir): 
"""Start the application under the code profiler.""" 
from werkzeug.contrib.profiler import ProfilerMiddleware 
app.wsgi_app = ProfilerMiddleware(app.wsgi_app, restrictions=[length], 
profile dir=profile_dir) 








app.run(debug=False) 


这 个 命令 通过 应 用 的 wsgi_app 属性 ， 把 Werkzeug 的 ProfilerMiddleware 中 间 件 依附 到 应 
用 上 。WSGI 中 间 件 在 Web 服务 器 把 请 求 分 派 给 应 用 时 调用 ， 可 用 于 修改 处 理 请 求 的 方 
式 。 这 里 通过 中 间 件 捕获 分 析 数 据 。 注 意 ， 随 后 通过 app.run() 方法 ， 以 编程 的 方式 启动 
应 用 。 








如 果 你 从 GitHub 上 克隆 了 这 个 应 用 的 Git 仓库 ， 那 么 可 以 执行 git checkout 
16b 检 出 应 用 的 这 个 版 本 。 

















使 用 flask profite 命令 启动 应 用 后 ， 控 制 台 会 显示 每 条 请 求 的 分 析 数 据 ， 其 中 包含 
运行 最 慢 的 25 个 国 数 。- -Length 选项 可 以 修改 报告 中 显示 的 国 数 数量 。 如 果 指 定 了 
--profile-dir 选项 ， 每 条 请 求 的 分 析 数 据 会 保存 到 指定 目录 下 的 一 个 文件 中 。 分 析 器 输 
出 的 数据 文件 可 用 于 生成 更 详细 的 报告 ， 例 如 调用 图 。Python 分 析 器 的 详细 信息 请 参阅 官 
方 文档 (https://docs.python.org/2/library/profile.html) 。 


现在 我 们 完成 了 部 署 前 的 准备 工作 。 在 下 一 章 ， 你 将 了 解 部 署 应 用 的 大 致 过 程 。 
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部 着 





Flask 自 带 的 Web 开发 服务 器 不 够 稳健 、 安 全 和 高 效 ， 不 适合 在 生产 环境 中 使 用 。 本 章 介 
绍 几 种 不 同 的 Flask 应 用 部 署 方式 。 


17.1 部 署 流程 


不 管 使 用 哪 种 托管 方案 ， 应 用 安装 到 生产 服务 器 上 之 后 ， 都 要 执行 一 系列 任务 ， 其 中 就 包 
括 创建 或 更 新 数据 库 表 。 

如 果 每 次 安装 或 升级 应 用 都 手动 执行 这 些 任务 ， 那 么 会 容易 出 错 ， 也 浪费 时 间 。 
以 在 flasky.py 中 添加 一 个 命令 ， 自 Be HO 

示例 17-1 实现 了 一 个 适用 于 Flasky 的 deploy 命令 。 

示例 17-1 flasky.py: deploy 命令 


from flask_migrate import Upgrade 
from app.models import Role, User 




















Ba 











此 ， 可 








@manager .Command 

def deploy(): 
"Run depLoyment tasks.""" 
# 把 数据 库 了 迁移 到 最 新 修订 版 本 
upgrade() 


# 创建 或 更 新 用 户 角色 


Role.insert_roles() 














# 确保 所 有 用 户 都 关注 了 他 们 自己 
User .add_self_follows() 
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这 个 命令 调用 的 函数 之 前 都 已 经 定义 好 了 ， 现 在 只 不 过 是 在 一 个 命令 中 集中 调用 ， 以 简化 
部 署 应 用 的 过 程 。 














如 果 你 从 GitHub 上 克隆 了 这 个 应 用 的 Git 仓库 ， 那 么 可 以 执行 gtt checkout 
17a 检 出 应 用 的 这 个 版 本 。 











定义 这 些 函 数 时 考虑 到 了 多 次 执行 的 情况 ， 所 以 即使 多 次 执行 也 不 会 产生 问题 。 每 次 安装 
或 升级 应 用 时 只 需 运 行 deploy 命令 ， 无 须 担 心 运行 的 时 机 不 当 而 导致 的 副作用 。 


17.2 ”把 生产 环境 中 的 错误 写 入 日 志 


在 调试 模式 中 运行 的 应 用 发 生 错误 时 ，Werkzeug 的 交互 式 调试 器 会 出 现 。 网 页 中 会 显示 错 
误 的 栈 跟 踪 ， 而 且 可 以 查看 源码 ， 甚 至 还 能 使 用 Flask 的 网 页 版 交互 调试 器 在 每 个 栈 帧 的 
上 下 文中 执行 表达 式 。 

调试 器 是 开发 过 程 中 调试 问题 的 优秀 工具 ， 但 显然 不 能 在 生产 环境 中 使 用 。 生 产 环境 中 发 
生 的 错误 会 被 静默 掉 ， 取 而 代 之 的 是 向 用 户 显示 一 个 500 错误 页 面 。 不 过 幸好 错误 的 栈 跟 
踪 不 会 完全 丢失 ， 因 为 Flask 会 将 其 写 入 日 志文 件 。 


在 应 用 启动 过 程 中 ，Flask 会 创建 一 个 Python 的 logging.Logger 类 实例 ， 并 将 其 附属 到 应 
用 实例 上 ， 通 过 app.tLogger 访问 。 在 调试 模式 中 ,日 志 记 录 器 把 日 志 写 入 控制 台 ; 但 在 生 
产 模式 中 ， 默 认 情 况 下 没有 配置 日 志 的 处 理 程序 ， 所 以 如 果 不 添 加 处 理 程序 ， 就 不 会 保存 
日 志 。 示 例 17-2 中 的 改动 配置 一 个 日 志 处 理 程序 ， 把 生产 模式 中 出 现 的 错误 通过 电子 邮件 
发 送 给 FLASKY_ADMIN 设置 的 管理 员 。 


示例 17-2 config.py: 应 用 出 错时 发 送 电子 邮件 
class ProductionConfig(Config): 
六 
@classmethod 
def init app(cls, app): 
Config.init_app(app) 
















































































# 出 错时 邮件 通知 管理 员 

import logging 

from logging.handlers import SMTPHandler 

credentials = None 

secure = None 

if getattr(cls, 'MAIL_USERNAME', None) is not None: 
credentials = (cls.MAIL_USERNAME, cls.MAIL_PASSWORD) 
if getattr(cls, 'MAIL_USE_TLS', None): 

secure = () 

mail_handler = SMTPHandler( 
mailhost=(cls.MAIL_SERVER, cls.MAIL_PORT), 
fromaddr=cls.FLASKY_MAIL_SENDER, 
toaddrs=[cls.FLASKY_ADMIN], 
subject=cls.FLASKY_MAIL_SUBJECT_PREFIX + ' Application Error', 
credentials=credentials, 
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secure=secure) 
mail_handler .setLeveL(Logging.ERROR) 
app. Logger .addHandler (mail_handler) 


你 可 能 还 记得 ， 所 有 配置 类 都 有 一 个 init_app() 静态 方法 ， 在 create_app() 方法 中 调用 ， 
但 目前 还 没 用 到 。 现 在 ， 在 ProductionConfig 类 的 init_app() 方法 中 ， 我 们 为 应 用 日 志 记 
录 器 配置 了 一 个 处 理 程序 ， 把 错误 通过 电子 邮件 发 给 指定 的 收 件 人 。 

电子 邮件 日 志 记录 器 的 日 志 等 级 被 设 为 logging.ERROR， 所 以 只 有 发 生 严 重 错 误 时 才 会 发 
送 电 子 邮 件 。 通 过 添加 适当 的 日 志 处 理 程序 ， 可 以 把 等 级 较 轻 缓 的 日 志 消 息 写 入 文件 、 系 
统 日 志 或 支持 的 其 他 目的 地 。 日 志 的 处 理 方法 很 大 程度 上 依赖 于 应 用 所 在 的 托管 平台 。 


















































如 果 你 从 GitHub 上 克隆 了 这 个 应 用 的 Git 仓库 ， 那 么 可 以 执行 gtt checkout 
17b 检 出 应 用 的 这 个 版 本 。 





17.3 云 部 署 


如 今 流 行 把 应 用 托管 在 “云端 "， 不 过 这 有 多 层 意 思 。 最 简单 的 情况 下 ， 云 托管 的 意思 是 
把 应 用 部 署 到 一 台 或 多 台 虚 拟 服务 器 上 。 虚 拟 服务 器 操作 起 来 的 感受 与 物理 设备 很 像 ， 但 
却 是 由 云 服 务 公司 管理 的 虚拟 设备 。AWS (Amazon Web Services) 提供 的 EC2 服务 就 是 
这 样 的 服务 器 。 把 应 用 部 署 到 虚拟 服务 器 上 的 方法 与 部 署 到 传统 的 专用 服务 器 上 的 方法 
(本 章 后 文 将 讨论 ) 类 似 。 

更 高 级 的 部 署 方 法 是 基于 容器 。 一 个 容器 把 应 用 隔离 在 一 个 映像 (image) 中 ， 里 面包 含 
应 用 及 其 全 部 依赖 。 你 可 以 安装 容器 平台 ， 例 如 Docker， 在 支持 的 任何 系统 中 安装 并 运行 
预先 生成 好 的 容器 映像 。 


另 一 种 部 署 方式 ， 正 式 的 说 法 是 平台 即 服务 (PaaS，platform as a service) ， 它 让 应 用 开发 
者 从 安装 和 维护 运行 应 用 的 软 硬 件 平台 的 日 常 工作 中 解脱 出 来 。 在 Paas 模型 中 ， 服 务 提 
供 商 完全 接管 了 运行 应 用 的 平台 。 应 用 开发 者 只 需 把 应 用 代码 上 传 到 服务 提供 商 维 护 的 服 
务 器 中 ， 整 个 过 程 往往 只 需 几 秒 钟 。 多 数 PaaS 提供 商都 支持 按 需 添加 或 删除 服务 器 ， 动 
态 “ 缩 放 ” 应 用 ， 以 满足 不 同 量 级 的 请 求 。 


本 章 余 下 的 内 容 将 介绍 如 何 把 应 用 部 署 到 Heroku 中 ， 如 何 使 用 Docker 容器 部 署 ， 最 后 再 
介绍 适用 于 专用 服务 器 和 虚拟 服务 器 的 传统 部 署 方 式 。 


17.4 Heroku 平 台 


Heroku 是 最 早出 现 的 Paas 提供 商 之 一 ， 从 2007 年 就 开始 运营 。Heroku 平台 的 灵活 性 极 
高 ， 且 支持 多 种 编程 语言 (包括 Python)。 若 想 把 应 用 部 署 到 Heroku 上 ， 开 发 者 要 使 用 
Git 把 应 用 推送 到 Heroku 特殊 的 Git 服务 器 上 。 这 个 服务 器 将 自动 触发 安装 、 升 级 、 配 置 
和 部 署 等 操作 。 
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Heroku 使 用 名 为 dyno 的 计算 单元 衡量 用 量 ， 并 以 此 为 依据 收取 服务 费用 。 最 常用 的 dyno 
类 型 是 Web dyno， 表 示 一 个 Web 服务 器 实例 。 如 果 想 增加 处 理 请 求 的 能 力 ， 可 以 部 署 多 
个 Web dyno， 每 个 dyno 运行 一 个 应 用 实例 。 另 一 种 dyno 类 型 是 Worker dyno， 用 于 执行 
后 台 作 业 或 其 他 辅助 任务 。 


Heroku 提供 了 大 量 的 插件 和 扩展 ， 可 用 于 数据 库 、 电 子 邮件 和 其 他 很 多 服务 。 下 面 各 节 将 
展开 说 明 把 Flasky 部 署 到 Heroku 上 的 具体 步 又。 


17.4.1 准备 工作 


若 想 使 用 Heroku， 应 用 必须 存 入 Git 仓库 。 如 果 你 的 应 用 托管 在 像 GitHub 或 Bitbucket 这 
样 的 远程 Git 服务 器 上 ， 那 么 克隆 应 用 后 会 创建 一 个 本 地 Git 仓库 ， 可 无 颖 用 于 Heroku。 
如 果 你 的 应 用 没有 存 入 Git 仓库 ， 那 么 必须 在 开发 设备 上 创建 一 个 仓库 。 


如 果 你 计划 把 应 用 托管 在 Heroku 上 ， 最 好 从 开发 伊始 就 使 用 Git。GitHub 的 
帮助 指南 (https://help.github.com/) 中 有 针对 3 种 主流 操作 系统 的 安装 及 设 
置 说 明 。 





























1. 注册 Heroku 账 户 
在 使 用 Heroku 提供 的 服务 之 前 ， 你 必须 注册 一 个 账户 (https:/www.heroku.com/)。Heroku 
有 免费 套餐 ， 人 允许 托管 几 个 简单 的 应 用 ， 非 常 适合 做 实验 。 
2. 安装 Heroku CLI 
为 了 使 用 Heroku 服务 ， 必 须 安装 Heroku CLI (https://devcenter.heroku.com/articles/heroku-cli) 。 
这 是 一 个 命令 行 客户 端 ， 负 责 处 理 你 与 服务 的 交互 。Heroku 为 3 大 主流 操作 系统 都 提供 了 
安装 程序 。 
安装 好 Heroku CLI 之 后 ， 首 先 要 通过 heroku login 命令 验证 自己 的 Heroku 账户 : 

$ heroku Login 

Enter your Heroku credentials. 


Email: <your-email-address> 
Password: <your-password> 








别 忘 了 把 你 的 SSH 公 钥 上 传 到 Heroku， 这 样 才 能 使 用 git push 命令 。 正 
常情 况 下 ，login 命令 会 自动 创建 并 上 传 SSH 公 钥 ,但 也 可 以 使 用 heroku 
keys:add 命令 单独 上 传 公 钥 或 者 上 传 额外 所 需 的 公 钥 。 























3. 创建 应 用 
接 下 来 要 创建 应 用 。 在 此 之 前 ， 应 用 要 纳入 Git 源码 控制 。 如 果 你 一 直 使 用 GitHub 仓库 学 
习 书 中 的 代码 ， 那 么 就 已 经 有 一 个 Git 仓库 了 ， 否 则 要 自己 创建 一 个 。 然 后 ， 在 应 用 的 顶 
级 目录 中 执行 下 述 命令 ， 在 Heroku 中 注册 你 的 应 用 : 

$ heroku create <appname> 


Creating <appname>... done 
https://<appname>.herokuapp.com/ | https://git.heroky.com/<appname>.git 
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Heroku 应 用 的 名 称 在 所 有 客户 中 必须 是 独一无二 的 ， 因 此 你 必须 想 一 个 没 被 其 他 应 用 占用 
的 名 称 。 如 create 命令 的 输出 所 示 ， 部 署 后 应 用 可 通过 https://<appname>.herokuapp.com 
访问 。Heroku 也 支持 为 应 用 设置 自 定 义 域 名 。 


在 创建 应 用 的 过 程 中 ，Heroku 会 为 你 的 应 用 创建 一 个 专用 的 Git 服务 器 ， 地 址 为 https://git. 
heroku.com/<appname>.git。create 命令 调用 git remote 和 过 加 为 本 地 Git 仓 
库 的 远程 服务 器 ， 名 为 heroku。 
$ git remote show heroku 
* remote heroku 
Fetch URL: https://git.herokuy.com/<appname>.git 


Push URL: https://git.herokuy.com/<appname>.git 
HEAD branch: (unknown) 


必须 设置 FLASK_APP 环境 变量 才能 使 用 flask 命令 。 为 了 确保 在 Heroku 环境 中 全 、 
任何 命令 ， 最 好 注册 这 个 环境 变量 ， 让 Heroku 在 执行 与 应 用 有 关 的 命令 时 自动 设置 。 
一 步 使 用 config 命令 操作 : 

$ heroku config:set FLASK_APP=fLasky.py 


Setting FLASK_APP and restarting <appname>... done, v4 
FLASK_APP: flasky.py 


4. 配置 数据 库 
Heroku 以 扩展 形式 支持 Postgres 数据 库 。Heroku 的 免费 套餐 包含 一 个 小 型 数据 库 
存储 !1 万 行 记 录 。 执 行 下 述 命令 ， 为 应 用 绑 定 一 个 Postgres 数据 库 : 
$ heroku addons:create heroku-postgresqL:hobby-dev 
Creating heroku-postgresql:hobby-dev on <appname>... free 
Database has been created and is available 
! This database is empty. If Upgrading，you can transfer 
! data from another database with pg:copy 


Created postgresql-cubic-41298 as DATABASE_URL 
Use heroku addons:docs heroku-postgresql to view documentation 


从 输出 可 以 看 到 ， 应 用 在 Heroku 平台 中 运行 时 ， 可 以 通过 DATABASE_URL 环境 变量 获取 数 
据 库 的 地 址 和 凭据 。 这 个 变量 的 值 是 个 URL， 与 SQLAlchemy 要 求 的 格式 完全 一 样 。 回 想 
一 下 config.py 脚本 的 内 容 ， 如 果 设 定 了 DATABASE_URL， 就 使 用 其 中 保存 的 值 ， 所 以 现在 应 
用 可 以 自动 连接 到 Postgres 数据 库 。 


5. 配置 日 志 


之 前 我 们 实现 了 通过 电子 邮件 发 送 重大 错误 消息 的 功能 ， 除 此 之 外 ， 配 置 其 他 轻 缓 等 级 的 
消息 也 尤为 重要 。 个 很 好 的 例子 是 第 16 章 添加 的 数据 库 缓慢 查询 警告 消息 。 


Heroku 把 应 用 写 入 stdout 或 stderr 的 输出 视 为 日 志 ， 因 此 要 添加 相应 的 日 志 处 理 程序 。 
Heroku 会 捕获 输出 的 日 志 ， 在 Heroku CLI 中 可 以 使 用 heroku Logs 命令 查看 。 


日 志 的 配置 可 添加 到 ProductionConfig 类 的 init_app() 静态 方法 中 ， 但 由 于 这 种 日 志 处 理 


方式 是 Heroku 专用 的 ， 最 好 专门 为 这 个 平台 新 建 一 个 配置 类 ， 把 ProductionConfig 作为 
不 同类 型 生产 平台 的 基 类 。HerokuConfig 类 的 定义 如 示例 17-3 所 示 。 
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示例 17-3 config.py: Heroku 的 配置 类 


class HerokuConfig(ProductionConfig): 
@classmethod 
def init app(cls, app): 
ProductionConfig.init_app(app) 


# 输出 到 stderr 

import logging 

from logging import StreamHandler 
file_handler = StreamHandler() 
file_handler.setLevel(logging.INFO) 
app. Logger .addHandler (file_handler) 


Heroku 运行 应 用 时 ， 要 知道 该 使 用 这 个 新 配置 。flasky.py 脚本 创建 的 应 用 实例 通过 环境 
变量 FLASK_CONFIG 决定 使 用 哪个 配置 ， 所 以 我 们 要 在 Heroku 的 环境 中 正确 设 定 这 个 变量 。 
Heroku 平台 中 的 环境 变量 使 用 Heroku 客户 端的 config:set 命令 设 定 : 

$ heroku config:set FLASK_CONFIG=heroku 


Setting FLASK_CONFIG and restarting <appname>... done, v4 
FLASK_CONFIG: heroku 


为 了 提升 应 用 的 安全 性 ， 最 好 为 应 用 的 密 钥 配置 一 个 难 猿 的 字符 串 ， 用 于 签署 用 户 会 话 
和 身份 验证 令 牌 。Config 基 类 中 的 SECRET_KEY 属性 就 是 这 个 用 途 ， 如 果 有 同名 环境 变量 
就 使 用 变量 的 值 。 在 开发 设备 中 可 以 不 设 定 这 个 变量 ， 而 是 在 Config 类 中 硬 编码 一 个 值 。 
但 是 在 生产 平台 上 必须 设置 一 个 特别 难 猜 的 密 钥 ， 不 能 让 任何 人 知道 ， 因 为 一 旦 密 钥 汇 
露 ， 攻 击 者 便 能 伪造 用 户 会 话 的 内 容 或 生成 有 效 的 令 牌 。 为 了 确保 密 钥 的 安全 性 ， 只 需 把 
SECRET_KEY 环境 变量 设 为 一 个 唯一 的 字符 串 ， 但 不 存储 在 任何 地 方 : 

$ heroku config:set SECRET_KEY=d68653675379485599f7876a3b469a57 


Setting SECRET_KEY and restarting <appname>... done, v4 
SECRET_KEY: d68653675379485599f7876a3b469a57 


密 钥 用 的 随机 字符 串 有 多 种 生成 方法 ， 使 用 Python 可 以 这 样 生成 : 


(venv) $ python -c "import uuid; print(uuid.uuid4().hex)" 
d68653675379485599f7876a3b469a57 


6. 配置 电子 邮件 

Heroku 没有 提供 SMTP 服务 器 ， 所 以 我 们 要 配置 一 个 外 部 服务 器 。 有 很 多 第 三 方 扩展 能 把 
适用 于 生产 环境 的 邮件 发 送 服务 集成 到 Heroku 中 ， 但 对 于 测试 和 评估 而 言 ， 使 用 继承 自 
Config 基 类 的 Gmail 配置 已 经 足够 了 。 

因为 直接 把 安全 密令 写 入 脚本 存在 安全 隐患 ， 所 以 我 们 把 访问 Gmail SMTP 服务 器 的 用 户 
名 和 密码 保存 在 环境 变量 中 (最 好 别 使 用 你 个 人 的 电子 邮件 账户 ， 可 以 为 测试 注册 一 个 临 
时 账户 ) : 


$ heroku config:set MAIL_USERNAME=<your-gmail-username> 
$ heroku config:set MAIL_PASSWORD=<your-gmail-password> 


7. 添加 顶层 需求 文件 
Heroku 从 应 用 顶级 目录 下 的 requirements.txt 文件 中 加 载 包 依 赖 。 这 个 文件 中 的 所 有 依赖 都 
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会 在 部 署 过 程 中 导入 Heroku 创建 的 虚拟 环境 。 


Heroku 的 需求 文件 必须 包含 应 用 在 生产 环境 中 使 用 的 所 有 通用 依赖 ， 以 及 让 SQLAlchemy 
能 访问 Postgres 数据 库 的 psycopg2 包 。 我 们 可 以 在 requirements 目录 中 新 建 一 个 heroku.txt 文 
件 ， 写 入 这 些 依赖 ， 然 后 在 顶级 目录 中 的 requirements.txt 文件 里 导入 ， 如 示例 17-4 所 示 。 


示例 17-4 requirements.txt: Heroku 需求 文件 


-rT requirements/heroku.txt 


8. 使 用 Flask-SSLify 启 用 安全 的 HTTP 

前 文 多 次 说 到 ， 用 户 通 过 Web 表单 提交 的 用 户 名 和 密码 ， 有 被 恶意 的 第 三 方 截获 的 风险 。 
在 开发 过 程 中 ， 这 不 是 什么 问题 ， 但 是 把 应 用 部 署 到 生产 服务 器 上 之 后 ， 我 们 要 设法 降低 
这 种 风险 。 为 了 避免 用 户 的 凭据 在 传输 过 程 中 泄露 ， 有 必要 使 用 安全 的 HTTP， 使 用 公 钥 
加 密 客户 端 和 服务 器 之 间 的 所 有 通信 。 

无 须 任何 配置 ，Heroku 中 的 所 有 应 用 都 能 通过 http:// 和 https:// 访问 为 你 分 配 的 二 级 域名 。 
因为 这 是 Heroku 的 域名 ， 所 以 使 用 的 是 Heroku 的 SSL 证 书 。 因 此， 为 了 确保 应 用 的 安 
全 ， 我 们 只 需 拦截 发 给 http:/ 的 请 求 ， 将 其 重 定向 到 https://。 而 这 正 是 Flask-SSLify 扩展 
的 功能 。 

一 如 既往 ，Flask-SSLify 使 用 pip 安装 : 

















(venv) $ pip install flask-sslify 
然后 在 应 用 的 工厂 函数 中 激活 这 个 扩展 ， 如 示例 17-5 所 示 。 
示例 17-5 app/_init .py: 把 所 有 请 求 重 定向 到 安全 的 HITP 协议 


def create_app(config_name): 





if app.config['SSL_REDIRECT']: 
from flask_sslify import SSLify 
sslify = SSLify(app) 

i 


对 SSL 的 支持 只 需 在 生产 模式 中 启用 ， 而 且 仅 当 平台 支持 时 才 启 用 。 为 了 便于 启 停 SSL， 
我 们 添加 了 一 个 名 为 SSL_REDIRECT 的 环境 变量 。 在 Config 基 类 中 ， 把 它 设 为 False， 即 默 
认 不 启用 SSL 重 定向 。 在 HerokuConfig 类 中 却 要 禾 盖 这 个 变量 ， 启 用 重 定向 。 这 个 环境 
变量 的 实现 如 示例 17-6 所 示 。 


























示例 17-6 config.py: 配置 SSL 


class Config: 
Hs 
SSL_REDIRECT = False 


class HerokuConfig(ProductionConfig): 
类 
SSL_REDIRECT = True if os.environ.get('DYNO') else False 


在 HerokuConfig 类 中 ， 仅 当 DYNO 环境 变量 存在 时 ， 才 把 SSL_REDIRECT 的 值 设 为 True。DYNO 
变量 由 Heroku 设置 ， 因 此 使 用 Heroku 配置 在 本 地 测试 不 会 启用 SSL 重 定向 。 
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这 样 修改 之 后 ， 用 户 访问 Heroku 中 的 应 用 时 将 强制 使 用 SSL 连接 。 不 过 ， 还 需要 调整 一 
个 细节 ， 才 能 完善 此 项 功能 。 使 用 Heroku 时 ， 客 户 端 不 直接 连接 应 用 ， 而 是 通过 反 向 代 
理 服 务 器 连接 。 反 向 代理 服务 器 接收 来 自 多 个 应 用 的 请 求 ， 然 后 把 请 求 转发 给 相应 的 应 
用 。 在 这 种 架构 中 ， 只 有 代理 服务 器 运行 在 SSL 模式 下 。SSL 连接 到 代理 服务 器 即 告终 
结 ， 代 理 服 务 器 转发 给 应 用 的 请 求 是 不 加 密 的 。 如 此 一 来 ， 应 用 在 生成 绝对 URL 时 就 会 
出 现 问题 ， 因 为 Flask 应 用 收 到 的 请 求 对 象 针对 的 是 转发 后 的 请 求 ， 是 不 加 密 的 ， 而 不 是 
客户 端 通过 加 密 连 接 发 送 的 原始 请 求 。 

这 种 状况 会 导致 问题 ， 例 如 通过 电子 邮件 发 给 用 户 的 账户 确认 或 密码 重 设 链接 。 为 了 生成 
这 些 链接 的 绝对 URL， 我 们 要 调用 urL_for()， 并 指定 _externaL=True 参数 ， 但 是 Flask 
将 使 用 http:/ 协议 ， 因 为 Flask 不 知道 有 从 外 部 接收 加 密 连 接 的 反 向 代理 存在 。 

代理 服务 器 把 客户 端 发 来 的 原始 请 求 发 给 目标 Web 服务 器 时 ， 会 设 定 一 些 自 定义 的 HTTP 
首部 ， 我 们 可 以 利用 这 一 点 判断 用 户 是 不 是 通过 SSL 连接 应 用 的 。Werkzeug 提供 的 一 个 
WSGI 中 间 件 能 检查 代理 服务 器 设 定 的 这 些 自 定义 HITP 首部 ， 然 后 据 此 更 新 请 求 对 象 。 
例如 ，request.is_secure 的 值 会 反映 客户 端 发 给 反 向 代理 服务 器 的 请 求 的 加 密 状 态 ， 而 不 
是 代理 服务 器 转发 给 应 用 的 请 求 的 加 密 状 态 。 这 个 中 间 件 是 ProxyFix， 添 加 到 应 用 中 的 方 
法 如 示例 17-7 所 示 。 


示例 17-7 config.py: 添加 对 代理 服务 器 的 支持 


class HerokuConfig(ProductionConfig): 
Hs 
@classmethod 
def init app(cls, app): 
天 










































































# 处 理 反 向 代理 服务 器 设 定 的 首部 
from werkzeug.contrib.fixers import ProxyFix 
app.wsgi_app = ProxyFix(app.wsgi_app) 


这 个 中 间 件 添加 到 Heroku 配置 的 初始 化 方法 中 。WSGI 中 间 件 ， 例 如 ProxyFix， 初 始 化 
时 要 传人 WSGI 应 用 。 请 求 发 来 时 ， 在 处 理 请 求 之 前 ， 中 间 件 将 有 机 会 审查 环境 。 不 仅 
Heroku 需要 ProxyFix 中 间 件 ， 使 用 反 向 代理 服务 器 的 任何 部 署 方式 都 需要 。 
9. 运行 Web 生 产 服务 器 
Heroku 要 求 应 用 自己 局 动 Web 生产 服务 器 ， 并 在 PORT 环境 变量 设 定 的 端口 号 上 监听 请 求 。 
Flask 自 带 的 Web 开发 服务 器 不 适合 在 这 种 情况 下 使 用 ， 因 为 它 不 是 为 生产 环境 设计 的 服 
务 器 。 有 两 个 Web 服务 器 适合 在 生产 环境 中 使 用 ， 而 且 支 持 Flask 应 用 ， 它 们 是 Gunicom 
和 uWSGI。 
建议 你 在 本 地 虚拟 环境 中 安装 其 中 一 个 Web 服务 器 ， 以 便 在 类 似 Heroku 的 环境 中 测试 。 
例如 ， 可 通过 如 下 命令 安装 Gunicorn: 

(venv) $ pip install gunicorn 
然后 执行 下 述 命 令 ， 在 本 地 使 用 Gunicorn 运行 应 用 : 


(venv) $ gunicorn flasky:app 
[2017-08-03 23:54:36 -0700] [INF0] Starting gunicorn 19.7.1 



































[2017-08-03 23:54:36 -0700] [INFO] Listening at: http://127.0.0.1:8000 (68982) 
[2017-08-03 23:54:36 -0700] [INFO] Using worker: sync 
[2017-08-03 23:54:36 -0700] [INFO] Booting worker with pid: 68985 


flasky:app 告诉 Gunicorn 应 用 实例 的 位 置 ， 冒 号 前 面 的 部 分 是 实例 所 在 的 包 名 或 模块 名 ， 


冒号 后 面 的 部 分 是 应 用 实例 的 名 称 。 注 意 ，Gunicor 默认 使 用 8000 端口 ， 而 Flask 默认 使 
用 5000。 与 Flask 的 Web 开发 服务 器 一 样 ， 可 以 按 Ctrl+C 键 退出 Gunicorn。 











Gunicorn Web 服务 器 不 能 在 微软 Windows 中 运行 。 前 文 推荐 的 另 一 个 Web 
服务 器 ，uUWSGI， 可 以 在 Windows 中 运行 ， 但 是 它 难以 安装 ， 因 为 是 用 原 
生 代码 编写 的 。 如 果 你 想 在 Windows 系统 中 测试 Heroku 部 署 环境 ， 可 以 使 
用 Waitress (https://docs.pylonsproject.org/projects/waitress/en/latest/)。 它 也 是 纯 
Python Web 服务 器 ， 与 Gunicorn 有 很 多 相同 点 ， 只 不 过 完全 支持 Windows。 
Waitress 使 用 pip 安装 : 

(venv) $ pip install waitress 


Waitress Web 服务 器 使 用 waitress-serve 命令 启动 : 














(venv) $ waitress-serve --port 8000 flasky:app 


10. 添加 Procfile 文 件 

Heroku 需要 知道 使 用 哪个 命令 启动 应 用 。 这 个 命令 在 一 个 名 为 Procfile 的 特殊 文件 中 指 
定 。 这 个 文件 必须 放 在 应 用 的 顶级 目录 中 。 

示例 17-8 是 这 个 文件 的 内 容 。 

示例 17-8 ”Procfile: Heroku Procfile 文件 


web: gunicorn flasky:app 
Procfile 文件 内 容 的 格式 很 简单 : 一 行 指定 一 个 任务 ， 任 务 名 后 跟 一 个 冒号 ， 然 后 是 运 
行 这 个 任务 的 命令 。 名 为 web 的 任务 比较 特殊 ，Heroku 使 用 这 个 任务 启动 Web 服务 器 。 
Heroku 会 为 这 个 任务 提供 一 个 PORT 环境 变量 ， 用 于 设 定 应 用 监听 请 求 的 端口 。 如 果 环 境 
中 设 定 了 PORT 变量 ，Gunicorn 默认 就 使 用 那个 端口 ， 因 此 无 须 在 启动 命令 中 显 式 指定 。 


如 果 你 使 用 的 是 微软 Windows， 或 者 想 让 你 的 应 用 完全 兼容 Windows 平台 ， 
可 以 换 为 Waitress Web 服务 器 : 


web: waitress-serve --port=$PORT flasky:app 





























应 用 可 在 Procfile 中 使 用 web 之 外 的 名 称 声明 其 他 任务 。Procfile 中 的 每 个 任 
务 在 单独 的 dyno 中 启动 。 





























如 果 你 从 GitHub 上 克隆 了 这 个 应 用 的 Git 仓库 ， 那 么 可 以 执行 git checkout 
17c 检 出 应 用 的 这 个 版 本 。 如 果 你 使 用 的 是 微软 Windows， 那 么 可 以 执行 git 
checkout 17c-waitress， 检 出 使 用 Waitress Web 服务 器 (而 非 Gunicorn) 的 
应 用 版 本 。 











17.4.2 ”使 用 heroku _ Local 测试 


Heroku CLI 有 个 Locat 命令 ， 其 作用 是 在 本 地 以 非常 接近 Heroku 服务 器 的 环境 测试 应 用 。 
然而 ， 在 本 地 运行 应 用 时 ，FLASK_APP 等 环境 变量 就 不 再 是 环境 变量 了 。heroku local 命 
令 在 应 用 顶层 目录 下 的 .env 文件 中 寻找 配置 应 用 的 环境 变量 。 例 如 ，.env 文件 可 能 包含 如 

















下 变量 : 


FLASK_APP=fLasky.py 
FLASK_CONFIG=heroku 
MAIL_USERNAME=<your-gmail-username> 
MAIL_PASSWORD=<your-gmail-password> 





由 于 .env 文件 中 包含 密码 和 其 他 敏感 的 账户 信息 ， 
控制 。 











千 万 不 要 将 其 纳入 版 本 


启动 应 用 之 前 还 要 执行 部 署 任务 ， 创 建 数据 库 。 一 次 性 任务 可 以 使 用 tocal:run 命令 运行 : 


(venv) $ heroku local:run fLask deploy 

[OKAY] Loaded ENV .env File as KEY=VALUE Format 

INFO Context impl SQLiteImpl. 

INFO Will assume non-transactional DDL. 

INFO Running upgrade -> 38c4e85512a9, initial migration 
INFO Running upgrade 38c4e85512a9 -> 456a945560f6, login 


support 


INFO Running upgrade 456a945560f6 -> 190163627111, account confirmation 
INFO Running upgrade 190163627111 -> S56ed7d33de8d, user roles 
INFO Running upgrade S56ed7d33de8d -> d66f086b258, user information 


INFO Running upgrade d66f086b258 -> 198bQeebcf9, caching 


of avatar hashes 


INFO Running upgrade 198bQeebcf9 -> 1b966e7f4b9e, post model 
INFO Running upgrade 1b966e7f4b9e -> 288cd3dc5a8, rich text posts 
INFO Running upgrade 288cd3dc5a8 -> 2356a38169ea, followers 
INFO Running upgrade 2356a38169ea -> 51f5ccfba190, comments 


heroku local 命令 读 取 Procfile 的 内 容 ， 执 行 其 中 定义 的 任务 : 


(venv) $ heroku local 
[OKAY] Loaded ENV .env File as KEY=VALUE Format 
11:37:49 AM web.1 | [INFO] Starting gunicorn 19.7.1 


11:37:49 AM web.1 | [INFO] Listening at: http://0.0.0.0:5000 (91686) 


11:37:49 AM web.1 | [INFO] Using worker: sync 


11:37:49 AM web.1 | [INFO] Booting worker with pid: 91689 








这 个 命令 把 所 有 任务 的 日 志 输 出 整合 为 一 个 流 ， 在 控制 台 打 印 





| 


来 ， 每 一 行 前 都 有 时 间 蕉 





和 任务 名 。 


heroku local 命令 还 支持 使 用 多 个 dyno 模拟 应 用 的 伸缩 情况 。 
程 (worker) ， 每 一 个 职 程 监听 不 同 的 端口 : 


(venv) $ heroku local web=3 


下 述 命令 启动 3 个 Web 职 





17.4.3 ”执行 goit push 命 令 部 署 


部 署 过 程 的 最 后 一 步 是 把 应 用 上 传 到 Heroku 服务 器 。 在 此 之 前 ， 要 确保 所 有 改动 都 已 提 
交 到 本 地 Git 仓库 ， 然 后 执行 git push heroku master， 把 应 用 上 传 到 远程 仓库 heroku 


$ git push heroku master 

Counting objects: 502, done. 

Delta compression using up to 8 threads. 

Compressing objects: 100% (426/426), done. 

Writing objects: 100% (502/502), 108.03 KiB | 0 bytes/s, done. 
Total 502 (delta 303), reused 146 (delta 61) 








remote: Compressing source files... done. 
remote: Building source: 

remote: 

remote: ----- > Python app detected 

remote: ----- > Installing python-3.6.2 

remote: ----- > Installing pip 

remote: ----- > Installing requirements with pip 
remote: ----- > Discovering process types 
remote: Procfile declares types -> web 
remote: 

remote: ----- > Compressing... 

remote: Done: 49.4M 

remote: ----- > Launching... 

remote: Released v8 

remote: https://<appname>.herokuapp.com/ deployed to Heroku 
remote: 

remote: Verifying deploy... done. 

To https://git.herokyu.com/<appname>.git 

* [new branch] master -> master 





现在 应 用 已 经 部 署 好 ， 并 正在 运行 ， 但 还 不 能 正常 使 用 ， 因 为 还 没 执 行 deploy 命令 初始 化 
数据 库 表 。 这 个 命令 可 通过 Heroku CLI 执行 : 


$ heroku run flask depLoy 

Running flask deploy on <appname>... Up，run.3771 (Free) 

INFO [alembic.runtime.migration] Context impl PostgresqlImpl. 
INFO [alembic.runtime.migration] Will assume transactional DDL. 











创建 并 配置 好 数据 库 表 之 后 ， 重 启 应 用 ， 使 用 更 新 后 的 数据 库 : 


$ heroku restart 
Restarting dynos on <appname>... done 








至 此 ， 应 用 就 完全 部 署 好 了 ， 可 通过 https://<appname>.herokuapp.com 访问 。 
查看 应 用 的 日 志 
Heroku 会 捕获 应 用 输出 的 日 志 。 若 想 查 看 日 志 的 内 容 ， 使 用 Logs 命令 


$ heroku Logs 























在 测试 的 过 程 中 ， 还 可 以 使 用 下 述 命令 跟踪 日 志文 件 的 内 容 : 


$ heroku logs -t 


17.4.4 升级 后 重新 部 署 


升级 Heroku 应 用 时 要 重复 上 述 步 又 。 所 有 改动 都 提交 到 Git 仓库 之 后 ， 执 行 下 述 命令 进行 
升级 : 

$ heroku maintenance:on 

$ git push heroku master 

$ heroku run flask deploy 


$ heroku restart 
$ heroku maintenance:off 


Heroku CLI 提供 的 maintenance 命令 在 升级 过 程 中 下 线 应 用 ， 并 向 用 户 显示 一 个 静态 页 面 ， 
告知 网 站 很 快 就 能 恢复 。 这 样 能 避免 用 户 在 升级 的 过 程 访问 应 用 。 


17.5 Docker 容器 


现在 你 已 经 熟悉 Heroku 的 用 法 了 ， 这 是 一 种 相当 高 层级 的 部 署 方式 。 本 节 介 绍 如 何 使 用 
容器 ， 具 体 而 言 是 Docker 平台 。 容 器 没有 PaaS 自动 化 程度 高 ， 但 是 更 灵活 ， 而 且 不 限于 
特定 的 云 服 务 提 供 商 。 

容器 是 一 种 特殊 的 虚拟 设备 ， 运 行 在 宿主 操作 系统 的 内 核 之 上 。 与 标准 的 虚拟 设备 不 同 ， 
容器 没有 虚拟 化 的 内 核 和 硬件 。 因 为 虚拟 化 在 内 核 终止 ， 所 以 容器 比 虚 拟 设备 更 轻 量 、 更 
高 效 ， 但 是 要 求 操作 系统 支持 此 项 功能 。Linux 内 核 完全 支持 容器 。 




































































17.5.1 安装 Docker 


最 流行 的 容器 平台 是 Docker， 它 有 免费 社区 版 (Docker CE)， 也 有 订阅 式 企业 版 (Docker 
EE)。Docker 可 在 3 大 主流 桌面 操作 系统 中 安装 ， 也 可 以 在 云 服务 器 中 安装 。 若 想 开 发 并 
测试 容器 化 应 用 ， 最 简单 的 方法 是 在 开发 系统 中 安装 Docker CE。macOS 和 微软 Windows 
用 户 可 从 Docker 商店 中 下 载 一 键 安装 程序 (https://store.docker.com/search?offering=commu 
nity&type=edition) 。 这 个 页 面 还 有 针对 CentOS、Fedora、Debian 和 Ubuntu 等 Linux 发 行 版 
的 安装 说 明 。 

在 系统 中 安装 好 Docker CE 之 后 ， 便 可 以 在 终端 使 用 docker 命令 : 


$ docker version 





























Client: 

Version: 17.06.0-ce 
API version: 1.30 
Go version: go1.8.3 
Git commit: 02c1d87 
Built: Fri Jun 23 21:31:53 2017 
0S/Arch : darwin/amd64 
Server: 





Version: 17.06.0-ce 
API version: 1.30 (minimum version 1.12) 


Go version: go1.8.3 

Git commit: ”02c1d87 

Built: Fri Jun 23 21:51:55 2017 
0S/Arch : Linux/amd64 


Experimental: true 








Windows 版 Docker 需要 启动 微软 的 Hyper-V 功能 。 安 装 程序 通常 会 为 
你 启用 这 个 功能 ， 但 是 倘若 安装 后 无 法 正常 使 用 Docker， 首 先 应 该 检查 
Hyper-V 虚拟 机 监控 程序 (hypervisor) 。 注 意 ， 如 果 在 Windows 设备 中 启用 
了 Hyper-V， 其 他 虚拟 机 监控 程序 〈 例 如 Oracle 的 VirtualBox) 就 无 法 使 用 
了 。 如 果 你 的 系统 不 支持 Hyper-V 虚拟 化 ， 或 者 你 想 在 不 影响 其 他 虚拟 化 技 
术 的 前 提 下 使 用 Docker， 可 以 安装 Docker Toolbox (https://docs.docker.com/ 
toolbox/overview/) ， 这 是 旧 的 Windows 版 Docker， 基 于 VirtualBox 实现 。 


























17.5.2 ”构建 容器 映像 


使 用 容器 的 第 一 步 是 为 应 用 构建 一 个 容器 映像 。 映 像 是 容器 内 文件 系统 的 快照 ， 是 创建 新 
容器 的 模板 。 创 建 Docker 映像 的 指令 写 在 Dockerfile 文件 中 。 示 例 17-9 是 针对 本 书 示 例 
应 用 的 Dockerfile 文件 。 


示例 17-9 ”Dockerfile: 容器 映像 构建 脚本 
FROM python:3.6-alpine 








ENV FLASK_APP flasky.py 
ENV FLASK_CONFIG docker 


RUN adduser -D flasky 
USER flasky 


WORKDIR /home/fLasky 


COPY requirements requirements 
RUN python -m venv venv 
RUN venv/bin/pip install -r requirements/docker .txt 


COPY app app 
COPY migrations migrations 
COPY flasky.py config.py boot.sh ./ 


# 运行 时 配置 
EXPOSE 5000 
ENTRYPOINT ["./boot.sh"] 





tt 


Dockerfile 文件 中 可 以 使 用 的 构建 命令 参见 文档 (https://docs.docker.com/engine/reference/ 
builder/)。 其 实 ， 这 些 是 部 署 命令 ， 它 们 在 容器 的 文件 系统 (与 系统 隔离 ) 中 安装 并 配置 
应 用 。 








所 有 Dockerfile 文件 中 都 要 有 FROM 命令 ， 其 作用 是 指定 一 个 基 容 器 映像 ， 在 其 基础 上 构 
建 当 前 映像 。 多 数 情 况 下 都 使 用 Docker Hub (Docker 容器 映像 仓库 ) 中 公开 可 用 的 映像 。 
Docker Hub 中 有 针对 不 同 Python 解释 器 版 本 的 官方 映像 。 这 些 映像 在 操作 系统 中 安装 了 
Python。 指 定 映像 时 要 提供 名 称 和 标签 。Docker Hub 中 官方 的 Python 映像 名 为 python。 
可 在 Docker Hub 中 映像 的 页 面 查看 可 用 的 标签 。 对 python 映像 来 说 ， 标 签 用 于 指定 解释 
器 的 版 本 和 适用 的 平台 。 这 里 使 用 的 是 3.6 版 解释 器 ， 基 于 Alpine Linux 发 行 版 构建 。 容 
器 映像 经 常 使 用 Alpine Linux， 因 为 它 体 量 小 。 











macOS 和 Windows 版 Docker 能 运行 基于 Linux 的 容器 。 








ENV 命令 定义 运行 时 环境 变量 ， 其 参数 有 两 个 : 变量 名 及 其 值 。 这 个 命令 定义 的 环境 变量 
将 在 基于 这 个 映像 创建 的 容器 中 可 用 。 这 里 定义 了 flask 命令 所 需 的 FLASK_APP 变量 ， 以 
及 在 启动 时 配置 应 用 的 FLASK_CONFIG 配置 类 。 采 用 Docker 部 署 时 ， 我 们 将 使 用 一 个 新 
的 配置 ， 名 为 docker， 对 应 的 DockerConfig 类 如 示例 17-10 所 示 。 这 个 新 配置 类 继承 自 
ProductionConfig， 只 不 过 把 日 志 重 定向 到 stderr。Docker 将 自动 从 中 捕获 日 志 ， 通 过 
docker logs 命令 对 外 输出 。 














示例 17-10 config.py: Docker 配置 


class DockerConfig(ProductionConfig): 
@classmethod 
def init app(cls, app): 
ProductionConfig.init_ app(app) 


# 把 日 志 输 出 到 stderr 

import logging 

from logging import StreamHandler 
file_handler = StreamHandler() 
file_handler.setLevel(logging.INFO) 
app. Logger .addHandler (file_handler) 





config = { 
# ... 
'docker': DockerConfig, 
# 

} 





RUN 命令 在 容器 映像 的 上 下 文中 执行 指定 的 命令 。 在 示例 17-9 中 ， 第 一 个 RUN 命令 在 容器 
中 创建 一 个 名 为 flasky 的 用 户 。adduser 命令 由 Alpine Linux 提供 ， 在 FROM 命令 指定 的 基 
映像 中 可 用 。adduser 命令 的 -0 参数 禁止 命令 提示 用 户 输入 密码 。 


USER 命令 选择 以 哪个 用 户 的 身份 运行 容器 ， 以 及 Dockerfile 文件 中 后 续 的 命令 。Docker 默 
认 使 用 root 用 户 ， 但 是 如 无 必要 ， 一 般 建 议 切换 为 常规 用 户 。 

WORKDIR 命令 定义 应 用 所 在 的 顶层 目录 。 这 里 使 用 的 是 前 面 创建 的 flasky 用 户 的 家 目录 
(home directory) 。Dockerfile 文件 中 余下 的 命令 都 将 在 这 个 目录 中 执行 。 





























copy 命令 从 本 地 文件 系统 中 把 文件 复制 到 容器 的 文件 系统 中 。 这 里 复制 了 requirements， 
app 和 migrations 这 3 个 完整 的 目录 ， 以 及 应 用 顶层 目录 中 的 flasky.py、config.py 和 新 出 
现 的 boot.sh 文件 〈 稍 后 讨论 )。 


后 面 两 个 RUN 命令 创建 虚拟 环境 ， 并 在 里 面 安装 所 需 的 包 。 我 们 为 Docker 部 署 方式 专门 准 
备 了 一 个 需求 文件 ， 即 requirements/docker.txt。 这 个 文件 从 requirements/common.txt 中 导 
入 全 部 依赖 ， 在 此 基础 上 又 添加 了 Gunicorn， 在 Heroku 部 署 方式 中 用 作 Web 服务 器 。 


EXPOSE 命令 定义 服务 器 安装 在 容器 的 哪个 端口 上 。 启 动容 器 后 ，Docker 会 把 这 个 端口 映射 
到 宿主 设备 的 真实 端口 上 ， 以 便 容器 接收 外 部 世界 发 来 的 请 求 。 


最 后 一 个 命令 ENTRYPOINT 指定 启动 容器 时 如 何 运 行 应 用 。 我 们 把 前 面 复制 到 容器 中 的 
boot.sh 当 作 启动 脚本 。 这 个 文件 的 内 容 如 示例 17-11 所 示 。 


示例 17-11 bootsh: 容器 启动 脚本 
#!/bin/sh 
source venv/bin/activate 
flask deploy 
exec gunicorn -b 0.0.0.0:5000 --access-logfile - --error-logfile - flasky:app 


个 脚本 先 激 活 构 建 容器 的 过 程 中 创建 的 venv 虚拟 环境 ， 然 后 执行 本 章 前 面 为 应 用 定义 
deploy 命令 (部 署 到 Heroku 中 也 用 到 了 )。deploy 命令 创建 一 个 新 数据 库 ， 将 其 更 新 
到 最 新 版 本 ， 然 后 插入 默认 用 户 角色 。 我 们 没有 设 定 DATABASE_URL 环境 变量 ， 因 此 这 里 使 
用 的 是 SQLite 数据 库 。 最 后 ， 局 动 Gunicorn 服务 器 ， 监 听 5000 端口 。Docker 会 捕获 应 用 
的 所 有 输出 ， 将 其 写 入 日 志 ， 因 此 我 们 配置 Gunicorn， 把 访问 日 志和 错误 日 志文 件 都 写 入 
标准 输出 。 使 用 exec 命令 启动 Gunicorn 后 ，Gunicorn 了 运行 boot.sh 文件 的 
进程 。 这 是 因为 Docker 会 特别 留意 启动 容器 的 进程 ， 希 望 整个 生命 周期 内 它 都 是 主 进程 。 
如 果 这 个 进程 停止 运行 了 ， 容 器 也 就 停止 了 。 



























































如 果 你 从 GitHub 上 克隆 了 这 个 应 用 的 Git 仓库 ， 那 么 可 以 执行 qit checkout 
17d 检 出 应 用 的 这 个 版 本 。 





现在 ， 我 们 可 以 像 下 面 这 样 为 Flasky 构建 容器 映像 ; 


$ docker build -t flasky:latest . 
Sending build context to Docker daemon 51.08MB 
Step 1/14 : FROM python:3.6-alpine 

--> a6beab4fa70b 


Successfully built 930e17a89b42 
Successfully tagged flasky:latest 


docker build 命令 的 -t 参 数 指定 容器 映像 的 名 称 和 标签 ， 二 者 之 间 以 冒号 分 隔 。 标 签 经 常 
使 用 latest， 即 使 用 容器 映像 的 最 新 版 本 。build 命令 最 后 那个 点 号 把 当前 目录 设 为 构建 
过 程 中 的 顶级 目录 。Docker 将 在 这 个 目录 中 寻找 Dockerfile 文件 ， 而 且 容 器 映像 可 以 从 这 
个 目录 及 其 全 部 子 目录 中 复制 所 需 的 文件 。 
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docker build 命令 成 功 运 行 结 束 后 ， 本 地 映像 仓库 中 将 多 出 一 个 容器 映像 。 本 地 系统 中 映 
像 仓库 的 内 容 可 使 用 docker images 命令 查看 : 


$ docker images 








REPOSITORY TAG IMAGE ID CREATED SIZE 
flasky Latest 930e17a89b42 5 minutes ago 127MB 
python 3.6-alpine a6beab4fa70b 3 weeks ago 88.7MB 


这 个 命令 列 出 了 我 们 刚 构 建 的 flasky:Tlatest 映像 ， 以 及 Dockerfile 中 使 用 FROM 命令 引用 
的 Python 3.6 解释 器 映像 。 后 者 在 构建 过 程 中 由 Docker 下 载 并 安装 。 


17.5.3 ”运行 容器 
构建 好 应 用 的 容器 映像 后 就 可 以 运行 了 。 这 个 任务 很 简单 ， 执 行 docker run 命令 即 可 : 


$ docker run --name flasky -d -p 8000:5000 \ 
-e SECRET_KEY=57d40f677aff4d8d96df97223c74d217 \ 
-e MAIL_USERNAME=<your-gmail-username> \ 
-e MAIL_PASSWORD=<your-gmail-password> fLasky:Latest 


- -nane 选项 为 容器 指定 一 个 名 称 。 名 称 可 以 不 指定 ， 如 果 未 指定 ，Docker 将 使 用 随机 的 词 
生成 一 个 。 


-d 选项 指定 以 孤立 模式 启动 容器 ， 即 在 系统 的 后 台 作 业 中 运行 容器 。 非 狐 立 模式 下 的 容器 
作为 前 台 任 务 执行 ， 依 附 在 当前 控制 台 会 话 上 。 

-p 选项 把 宿主 系统 的 8000 端口 映射 到 容器 的 5000 端口 上 。Docker 给 了 我 们 充分 的 自由 ， 
允许 我 们 把 容器 端口 映射 到 宿主 系统 的 任何 端口 上 。 上 映射 后 ， 同 一 个 容器 上 映像 将 在 宿主 的 
不 同 端 口上 运行 两 个 或 多 个 容器 映像 实例 ， 而 各 实例 都 使 用 自己 的 虚拟 化 5000 端口 。 

-e 选项 定义 在 容器 的 上 下 文中 存在 的 环境 变量 ， 与 Dockerfile 文件 中 使 用 ENV 命令 定义 的 
环境 变量 共存 。SECRET_KEY 变量 的 值 确保 使 用 唯一 且 极 难 猜 到 的 密 钥 签署 用 户 会 话 和 令 
牌 。 你 要 为 这 个 变量 生成 唯一 的 密 钥 。MAIL_USERNAME 和 MAIL_PASSWORD 变量 配置 发 送 电 
子 邮 件 的 Gmail 服务 。 如 果 你 在 生产 环境 中 使 用 其 他 电子 邮件 服务 ， 可 能 还 要 定义 MAIL_ 


SERVER、MAIL_PORT 和 MAIL_USE_TLS 变量 。 
docker run 命令 的 最 后 一 个 参数 是 要 运行 的 容器 映像 的 名 称 和 标签 。 这 个 参数 的 值 应 该 与 
执行 docker build 命令 时 提供 给 -t 选项 的 值 一 致 。 


容器 在 后 台 启动 后 ，docker run 命令 会 在 控制 台 打印 容器 的 ID。 这 是 一 个 256 位 的 唯一 标 
识 符 ， 以 十 六 进 制 表示 。 需 要 引用 容器 的 命令 都 可 以 使 用 这 个 ID (其 实 只 需 提供 ID 的 前 
几 个 字符 ， 这 样 就 足以 唯一 标识 容器 了 )。 

为 了 确认 容器 确实 在 运行 中 ， 可 以 执行 docker ps 命令 查看 ; 


$ docker ps 
CONTAINER ID IMAGE CREATED STATUS PORTS NAMES 
71357ee776ae flasky:latest 4 secs ago Up 8 secs 0.0.0.0:8000->5000/tcp flasky 


既然 容器 已 经 运行 起 来 了 ， 那 么 现在 就 可 以 在 系统 的 8000 端口 上 访问 这 个 容器 化 应 用 。 
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本 地 使 用 的 地 址 是 http://localhost:8000， 在 同一 网 络 中 的 其 他 计算 机 上 则 使 用 http://<ip- 
address>:8000。 


若 想 停止 运行 容器 ， 执 行 docker stop 命令 : 


$ docker stop 71357ee776ae 


71357ee776ae 
stop 命令 只 停止 运行 容器 ， 但 不 从 系统 中 将 其 删除 。 如 果 想 删除 容器 ， 执 行 docker rm 
全 全 
aj: 


$ docker rm 71357ee776ae 
71357ee776ae 


这 两 个 命令 可 以 合并 为 docker rm -f: 


$ docker rm -f 71357ee776ae 
71357ee776ae 





17.5.4 ”审查 运行 中 的 容器 
容器 出 现 异常 时 ， 可 能 需要 调试 。 最 简单 的 调试 方法 是 在 应 用 中 添加 输出 日 志 的 语句 ， 然 
后 使 用 docker logs 命令 监控 运行 中 的 容器 。 
不 过 ， 有 些 情况 下 更 适合 在 运行 中 的 容器 里 打开 一 个 shell 会 话 ， 以 进行 更 深入 的 分 析 。 这 
个 任务 通过 docker exec 命令 操作 

$ docker exec -it 71357ee776ae sh 
执行 这 个 命令 后 ，Docker 将 使 用 sh (Unix shell) 打开 一 个 shell 会 话 ， 而 且 不 打 断 容器 的 
运行 。-it 选项 把 执行 这 个 命令 的 终端 会 话 与 新 启动 的 进程 连接 起 来 ， 让 shell 执行 交互 式 
操作 。 如 果 容 器 中 有 其 他 更 高 级 的 shell， 例 如 bash 或 Python 解释 器 ， 也 可 以 拿 来 用 。 
排查 容器 问题 的 常用 策略 是 创建 一 个 特殊 的 容器 ， 加 载 一 些 辅助 工具 ， 例 如 调试 器 ， 然 后 
在 shell 会 话 中 调用 。 


17.5.5 ”把 容器 映像 推送 到 外 部 注册 处 

把 容器 映像 存储 在 本 地 便于 开发 和 测试 应 用 ， 但 是 如 果 你 想 与 他 人 分 享 映 像 ， 就 要 把 映像 
推送 到 外 部 注册 处 服务 器 。 

Docker Hub 是 Docker 官方 映像 仓库 ， 这 是 一 项 便利 服务 ， 你 可 以 把 自己 的 映像 托管 在 这 
里 。Docker Hub 免费 账户 提供 无 限量 的 公开 容器 映像 存储 ， 不 过 只 能 存储 一 个 私有 映像 。 
如 果 想 增加 私有 了 映像 的 数量 ， 那 么 要 购买 收费 套餐 。 请 访问 https://hub.docker.com 创建 一 
个 Docker Hub 账户 。 


注册 好 Docker Hub 账户 后 ， 可 以 在 命令 行 中 使 用 docker Login 命令 登录 : 


$ docker login 
Login with your Docker ID to push and pull images from Docker Hub. 
Username: <your-dockerhub-username> 
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Password: <your-dockerhub-password> 
Login Succeeded 


若 想 登录 Docker Hub 之 外 的 容器 映像 仓库 ， 把 仓库 的 地 址 作为 参数 传 给 


docker Login 命令 。 


本 地 容器 映像 有 个 简单 的 名 称 。 若 想 把 映像 推送 到 Docker Hub， 上 映像 名 称 前 必须 加 
上 你 的 Docker Hub 账 户 名 ， 而 且 二 者 之 间 以 一 个 斜 线 分 隔 。 我 们 可 以 为 前 面 构建 的 
flLasky:Latest 映像 再 起 个 名 称 ， 以 便 推 送 到 Docker Hub。 这 个 任务 使 用 docker tag 命令 
操作 : 


$ docker tag flasky:latest <your-dockerhub-username>/fLasky:Latest 


然后 执行 docker push 命令 ， 把 映像 推送 到 Docker Hub: 


$ docker push <your-dockerhub-username>/fLasky:Latest 
现在 ， 这 个 容器 映像 公开 了 ， 任 何人 都 能 使 用 docker run 命令 基于 它 启动 一 个 容器 : 


$ docker run --name flasky -d -p 8000:5000 \ 
<your-dockerhub-username>/fLasky:Latest 


17.5.6 ”使 用 外 部 数据 库 


使 用 Docker 容器 部 署 Flasky 有 个 缺点 : 应 用 默认 使 用 的 SQLite 数据 库 在 容器 内 非常 难 升 
级 ， 因 为 容器 一 旦 停止 运行 ， 数据库 就 不 见 了 。 
更 好 的 方案 是 在 应 用 的 容器 之 外 托管 数据 库 服 务 器 。 这 样 升级 应 用 时 只 需 换个 新 容器 ， 数 
据 库 就 能 轻松 地 保留 下 来 。 
Docker 推荐 采用 模块 化 方式 构建 应 用 ， 一 个 容器 针对 一 个 服务 。MySQL、Postgres 等 很 多 
数据 库 服务 器 都 有 公开 可 用 的 容器 映像 。 使 用 docker run 命令 可 以 直接 把 其 中 任何 一 个 部 
署 到 系统 中 。 下 述 命令 把 MySQL 5.7 数据 库 服务 器 部 署 到 系统 中 : 
$ docker run --name mysqL -d -e MYSQL_RANDOM_ROOT_PASSWORD=yes \ 

-e MYSQL_DATABASE=fLasky -e MYSQL_USER=flasky \ 

-e MYSQL_PASSWORD=<database-password> \ 

mysql/mysql-server:5.7 
这 个 命令 创建 一 个 名 为 nysql 的 容器 ， 在 后 台 运 行 。-e 选项 设 定 几 个 环境 变量 ， 用 于 配置 
上 容器。 这些 变 量 及 其 他 可 用 变量 的 作用 参见 Docker Hub 中 这 个 MySQL 映像 的 页 面 。 上 述 
命令 为 数据 库 生 成 一 个 随机 的 root 密码 (启动 容器 后 可 使 用 docker logs mysql 命令 在 日 
志 中 查看 生成 的 密码 )， 然 后 创建 一 个 全 新 的 数据 库 ， 名 为 flasky， 并 赋予 flasky 用 户 访 
问 权 限 。 你 要 通过 MYSQL_PASSWORD 环境 变量 为 这 个 用 户 设 定 一 个 安全 的 密码 。 


为 了 连接 MySQL 数据 库 ，SQLAIlchemy 要 求 安装 一 个 被 它 支 持 的 MySQL 客户 端 包 ， 例 如 
pymysql。 你 可 以 把 这 个 包 添 加 到 docker.txt 需求 文件 中 。 
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如 果 你 从 GitHub 上 克隆 了 这 个 应 用 的 Git 仓库 ， 那 么 可 以 执行 git checkout 
17e 检 出 应 用 的 这 个 版 本 。 








修改 requirements/docker.txt 文件 后 要 重新 构建 容器 映像 : 


$ docker build -t flasky:latest . 


如 果 之 前 的 应 用 容器 还 在 运行 中 ， 那 么 执行 docker rm -f 命令 将 其 停止 并 删除 ， 然 后 启动 
一 个 新 容器 ， 运 行 更 新 后 的 应 用 : 
$ docker run -d -p 8000:5000 --Link mysql:dbserver \ 
-e DATABASE_URL=mysql+pymysql://flasky:<database-password>@dbserver/flasky \ 


-e MAIL_USERNAME=<your-gmail-username> -e MAIL_PASSWORD=<your-gmail-password> \ 
flasky: latest 


这 个 docker run 命令 有 两 个 新 增 项 。- -Link 选项 把 这 个 新 容器 与 一 个 现 有 的 容器 连接 起 
a -Link 选项 的 值 是 以 冒号 分 隔 的 两 个 名 称 ， 一 个 是 目标 容器 的 名 称 或 ID ， 另 一 个 是 在 

当前 容器 中 访问 目标 容器 所 用 的 别名 。 这 里 ， 目 标 容 器 是 mysql， 即 前 面 启动 的 那个 数据 
库容 器 。 在 这 个 新 Flasky 容器 中 ， 可 以 通过 dbserver 主机 名 访问 那个 容器 。 


数据 库 外 移 后 ， 还 要 设 定 DATABASE_URL 环境 变量 ， 值 为 mysql 容器 中 flasky 数据 库 
的 URL， 数 据 库 主机 名 使 用 别名 dbserver，Docker 会 将 其 解析 为 所 连接 的 容器 的 IP 
地 址 。 此 外 ， 在 mysql 容器 中 设置 的 MYSQL_PASSWORD 环境 变量 也 要 写 在 这 个 URL 中 。 
DATABASE_URL 的 值 将 覆盖 默认 的 SQLite 数据 库 ， 因 此 这 样 简 单 修改 之 后 ， 容 器 将 连接 
MySQL 数据 库 。 


Docker Hub 是 个 金 矿 ， 里 面 有 很 多 非常 实用 的 应 用 和 服务 的 Docker 映像 ， 
可 以 单独 使 用 ， 也 可 以 作为 自 定义 容器 的 基 上 映像。 你 会 发 现 ， 各 种 项 目 ( 包 
括 数据 库 、Web 服务 器 、 负 载 均衡 程序 、 编 程 语言 、 操 作 系 统 ， 等 等 ) 都 有 
官方 映像 。 

















17.5.7 ”使 用 Docker Compose 编 排 容 器 


容器 化 应 用 通常 由 多 个 容器 组 成 。 前 一 市 我 们 看 到 ， 主 应 用 和 数据 库 服 务 器 分 别 运行 在 单 
独 的 容器 中 。 应 用 变 复杂 后 ， 难 免 要 用 到 多 个 容器 。 有 些 应 用 可 能 需要 使 用 额外 的 服务 ， 
例如 消息 队列 或 缓存 。 另 一 些 应 用 可 能 采用 微服 务 架 构 ， 以 分 布 式 结构 部 署 多 个 小 型 子 应 
用 ， 分 别 运行 在 单独 的 容器 中 。 需 要 处 理 高 负载 或 者 需要 高 容错 能 力 的 应 用 可 能 想 进 行 伸 
缩 ， 在 负载 均衡 程序 背后 运行 多 个 实例 。 

随 着 应 用 所 需 的 容器 数量 不 断 增 长 ， 如 果 只 使 用 Docker， 那 么 管理 和 协调 容器 的 任务 将 变 
得 难 上 加 难 。 这 种 情况 下 ， 使 用 构建 在 Docker 基础 上 的 编排 框架 能 助 你 一 璧 之 力 。 

随 Docker 一 起 安装 的 Compose 工具 集 提 供 了 基本 的 编排 功能 。 使 用 Compose 时 ， 构 成 应 


用 的 各 容器 在 一 个 配置 文件 中 描述 ， 这 个 文件 通常 命名 为 docker-compose.yml。 这 里 定义 
的 所 有 容器 ， 可 以 使 用 docker-compose 命令 一 次 性 全 部 启动 。 
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针对 容器 化 Flasky 及 其 MySQL 服务 的 docker-compose.yml 文件 如 示例 17-12 所 示 。 


示例 17-12 ”docker-compose.yml: Compose 配置 文件 


version: '3' 
services: 
flasky: 

build: . 
ports: 

- "8000:5000" 
env_file: .env 
links: 

- mysql:dbserver 
restart: always 

mysql: 
image: "mysql/mysql-server:5.7" 
env_file: .env-mysql 
restart: always 


这 个 文件 的 内 容 使 用 YAML 格式 编写 。YAML 是 一 种 简洁 的 格式 ， 通 过 键 一 值 映射 和 列 
表 表 示 层 次 结构 。version 键 指定 使 用 哪个 版 本 的 Compose，services 键 在 子 元 素 中 定义 
应 用 的 各 个 容器 。Flasky 应 用 使 用 两 个 服务 ， 分 别名 为 flasky 和 mysql。 


flasky 服务 是 应 用 的 一 部 分 ， 名 下 的 子 键 指定 传 给 docker build 和 docker run 命令 的 参数 。 
build 键 指定 构建 目录 ， 即 Dockerfile 文件 所 在 的 目录 。ports 键 指定 网 络 端口 映射 。env_ 
file 键 是 为 容器 定义 多 个 环境 变量 的 便利 方式 。Links 键 连接 MySQL 容器 ， 对 外 的 主机 
名 为 dbserver。restart 键 设 为 always， 这 样 一 旦 容器 意外 退出 ，Docker 便 会 自动 重 局 容 
器 。 此 次 部 署 的 .env 文件 中 要 定义 下 述 变 量 ， 

FLASK_APP=fLasky.py 

FLASK_CONFIG=docker 

SECRET_KEY=3128b4588e7f4305b5501025c13ceca5 

MAIL_USERNAME=<your-gmail-username> 

MAIL_PASSWORD=<your-gmail-password> 

DATABASE_URL=mysql+pymysql://flasky:<database-password>@dbserver/flasky 


mysql 服务 的 结构 较 简 单 ， 因 为 这 个 服务 直接 使 用 现 有 的 映像 启动 ， 无 须 构 建 。image 键 指 
定 这 个 服务 所 用 容器 映像 的 名 称 和 标签 。 与 docker run 命令 一 样 ，Docker 会 从 容器 映像 注 
册 处 下 载 指定 的 映像 。env_file 和 restart 键 的 作用 与 flasky 容器 中 的 那些 键 相 仿 。 广 
意 ，MySQL 容器 的 环境 变量 存储 在 男 一 个 文件 中 ， 名 为 .env-mysql。 你 可 能 会 想 把 所 有 容 
器 的 环境 变量 都 放 在 .env 文件 中 ， 但 是 这 样 做 不 好 ， 最 好 禁止 一 个 容器 访问 另 一 个 容器 的 
机 密 信 息 。.env-mysql 文件 中 要 定义 下 述 环 境 变 量 : 

MYSQL_RANDOM_ROOT_PASSWORD=yes 

MYSQL_DATABASE=flasky 


MYSQL_USER=fLasky 
MYSQL_PASSWORD=<database-password> 
































.env 和 .env-mysql 文件 中 包含 密码 和 其 他 敏感 信息 ， 因 此 千 万 不 要 将 其 纳入 
版 本 控制 。 














docker-compose.yml 文件 的 完整 说 明 参 见 Docker 网 站 (https://docs.docker. 


com/compose/compose-file/) 。 


编排 系统 往往 有 个 问题 ， 即 不 能 以 正确 的 顺序 启动 各 个 容器 。 即 便 启动 的 顺序 是 正确 的 ， 
也 无 法 留 出 足够 的 时 间 ， 让 作为 其 他 高 层 容 器 基础 的 低层 容器 启动 和 初始 化 。 对 Flasky 来 
说 ， 要 先 启 动 mysql 容器 ， 这 样 启 动 flasky 容器 时 才 有 数据 库 可 用 ， 然 后 才能 连接 数据 
库 ， 应 用 数据 库 迁移 ， 最 后 再 启动 Web 服务 器 。 

Compose 能 按 正 确 的 顺序 启动 mysql 和 flasky 容器 ， 因 为 它 能 从 flasky 的 Links 键 检测 
到 二 者 之 间 的 依赖 关系 。MySQL 可 能 要 花 几 秒 钟 才能 启动 ， 但 是 Compose 不 会 等 待 。 设 
计 分 布 式 系统 时 ， 连 接 外 部 服务 器 时 一 般 都 会 多 试 儿 次 。 示 例 17-13 是 boot.sh 脚本 的 改进 
版 本 ， 启 动 flasky 容器 时 会 多 执行 几 次 flask deploy 命令 ， 直 到 成 功 更 新 数据 库 为 止 。 


示例 17-13 ”boot.sh: 等 数据 库 启动 


#!/bin/sh 
source venv/bin/activate 





while true; do 
flask deploy 


if [[ "$?" == "0" ]]; then 
break 
fi 
echo Deploy command failed, retrying in 5 secs... 
sleep 5 
done 
exec gunicorn -b :5000 --access-logfile - --error-logfile - flasky:app 


我 们 在 一 个 循环 中 不 断 重 试 执 行 flask deploy 命令 ,这样 容 器 便 有 了 一 定 的 容错 能 力 ,不 
要 求 数据 库 服 务 立 即 就 接受 请 求 。 
如 果 你 从 GitHub 上 克隆 了 这 个 应 用 的 Git 仓库 ， 那 么 可 以 执行 git checkout 


17f 检 出 应 用 的 这 个 版 本 。 此 外 ， 别 忘 了 创建 .env 和 .env-mysql 两 个 环境 文 
件 ， 并 在 其 中 配置 正确 的 变量 。 














配置 好 Compose 之 后 ， 可 以 使 用 docker-compose up 命令 启动 应 用 : 

$ docker-compose up -d --build 
docker-compose up 命令 的 --build 选项 指明 ， 应 该 在 启动 应 用 之 前 构建 。 这 是 为 了 构建 
flasky 容器 映像 。 构 建 好 映像 之 后 ， 将 按 顺序 启动 mysql 和 flasky 容器 。 与 使 用 单个 容器 
时 一 样 ，-d 选项 在 孤立 模式 下 启动 多 个 容器 。 几 秒 钟 之 后 ， 应 用 便 能 在 后 台 运 行 起 来 ， 此 
时 可 通过 http:Wlocalhost:8000 访问 应 用 。 
Compose 把 所 有 容器 的 日 志 合 并 为 一 个 流 ， 可 以 使 用 docker-compose logs 命令 查看 : 


$ docker-compose logs 
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如 果 你 想 持续 监控 日 志 流 的 话 ， 使 用 下 述 命令 : 
$ docker-compose logs -f 
docker -compose ps 命令 输出 运行 中 各 容器 的 概况 和 状态 : 


$ docker-compose ps 
Name Command State Ports 


fLasky_fLasky 1 ./boot.sh Up 0.0.0.0:8000->5000/tcp 
flasky_mysql_1 /entrypoint.sh mysqld Up 3306/tcp, 33060/tcp 


升级 应 用 时 ， 先 做 好 修改 ， 然 后 再 次 执行 前 面 用 于 启动 容器 的 docker-compose up 命令 即 
可 。 只 要 有 变化 ，Compose 就 会 重新 构建 应 用 容器 ， 把 旧 容 器 替换 掉 。 
若 想 停止 应 用 ， 使 用 docker-compose down 命令 。 如 果 想 把 容器 停止 并 删 掉 ， 使 用 docker- 


compose rm --stop --force 命令 。 


17.5.8 清理 旧 容 器 和 了 映像 
使 用 容器 的 时 间 一 长 ， 系 统 中 难免 会 堆积 一 些 不 再 需要 的 旧 容 器 或 映像 。 最 好 定期 检查 并 
清理 ， 以 免 占 用 系统 空间 。 
若 想 查看 系统 中 有 哪些 容器 ， 使 用 下 述 命令 : 

$ docker ps -a 
这 个 命令 将 列 出 运行 中 的 容器 ， 以 及 停止 了 但 仍 在 系统 中 的 容器 。 若 想 删 除 列表 中 的 某 个 
容器 ， 使 用 docker rm -f 命令 ， 并 指定 容器 的 名 称 或 ID: 

$ docker rm -f <name-or-id><name-or-id> ... 


若 想 查看 系统 中 存储 的 容器 映像 ， 使 用 docker images 命令 。 如 果 想 删除 某 个 映像 ， 使 用 


docker rmi 命令 。 


有 些 容器 会 在 宿主 计算 机 中 创建 虚拟 卷 (volume)， 作 为 容器 文件 系统 之 外 的 存储 空间 。 
例如 ，MySQL 容器 映像 把 所 有 数据 库 文件 都 放 在 一 个 卷 中 。 可 以 使 用 docker volune 1s 
命令 查看 系统 分 配 的 全 部 卷 。 若 想 删 除 某 个 不 再 使 用 的 卷 ， 使 用 docker volune rm。 


如 果 你 想 使 用 更 自动 化 的 清理 方式 ， 那 么 使 用 docker system prune --voLumes 命令 。 这 个 
命令 会 删除 所 有 不 再 使 用 的 映像 或 卷 ， 以 及 停止 后 依然 在 系统 中 的 容器 。 


17.5.9 在 生产 环境 中 使 用 Docker 


很 多 人 仅 把 Docker 当 作 开发 和 测试 平台 。 虽 然 前 面 几 市 讨论 的 技术 也 能 把 应 用 部 署 到 运 
行 Docker 的 生产 服务 器 上 ， 但 是 使 用 起 来 有 些 限制 ， 还 有 一 些 安全 问题 需要 考虑 。 


监控 和 提醒 


如 果 容 器 化 应 用 崩溃 了 怎么 办 ? Docker 能 重启 意外 退出 的 容器 ， 但 是 不 会 监控 容器 ， 
也 不 会 在 容器 不 稳定 时 发 出 警告 。 































































































日 志 


Docker 为 每 个 容器 维护 一 个 单独 的 日 志 流 。Compose 对 此 做 了 改善 ， 把 不 同 的 流 合并 
为 一 个 ， 但 是 没有 长 期 存储 机 制 ， 也 没有 搜索 或 过 普 功 能 。 


机 密 信息 管理 


通过 环境 变量 配置 密码 和 其 他 凭据 是 不 安全 的 ， 因 为 事先 配置 好 的 环境 变量 可 以 通过 
docker inspect 命令 或 API 访问。 


可 靠 性 和 伸缩 性 
为 了 提高 容错 能 力 ， 或 者 增加 负载 处 理 能 力 ， 要 在 一 个 或 多 个 负载 均衡 程序 背后 的 多 台 
主机 中 运行 多 个 应 用 实例 。 
这 些 局 限 一 般 可 以 通过 构建 在 Docker 基础 上 的 更 精巧 的 编排 框架 或 其 他 容器 运行 时 来 克 
服 。Docker Swarm ( 现 已 并 入 Docker) 、Apache Mesos 和 Kubernetes 等 框架 有 助 于 构建 稳 
健 的 容器 部 署 方案 。 


17.6 ”传统 部 署 方式 


我 们 介绍 了 如 何 使 用 Heroku 和 Docker 来 部 署 应 用 。 这 还 不 是 完整 的 部 署 策 略 ， 本 市 将 介 
绍 传统 托管 方式 。 采 用 这 种 方式 部 署 应 用 的 话 ， 要 购买 或 租用 服务 器 (物理 服务 器 或 虚拟 
服务 器 ) ， 然 后 在 服务 器 上 手动 设置 所 有 需要 的 组 件 。 这 显然 是 最 费力 的 部 署 方式 ， 但 是 
如 果 能 通过 终端 连接 生产 服务 器 的 硬件 ， 也 还 算是 个 不 错 的 选择 。 下 面 各 节 简 要 说 明 其 中 
涉及 的 工作 。 


17.6.1 架设 服务 器 

在 能 够 托管 应 用 之 前 ， 在 服务 器 上 必须 完成 多 项 管理 任务 。 

。 安装 数据 库 服 务 器 ， 例 如 MySQL 或 Postgres。 也 可 使 用 SQLite 数据 库 ， 但 由 于 它 在 修 
改 现 有 的 数据 库 模 式 方 面 有 种 种 限制 ， 不 建议 在 生产 服务 器 中 使 用 。 

。 安装 邮件 传输 代理 (mail transport agent，MTA)， 例 如 Sendmail 或 Postfix， 用 于 向 用 
户 发 送 邮件 。 不 要 妄图 在 线 上 应 用 中 使 用 Gmail， 因 为 这 个 服务 的 配额 少 得 可 怜 ， 而 且 
服务 条 款 明确 禁止 商用 。 

。 安装 适用 于 生产 环境 的 Web 服务 器 ， 例 如 Gunicorn 或 uWSGI。 

。 安装 一 个 进程 监控 工具 ， 例 如 Supervisor， 在 服务 器 月 涡 或 恢复 电力 后 立即 重启 。 

。 为 了 启用 安全 的 HTTP， 安 装 并 配置 SSL 证 书 。 

。 (可 选 ， 但 强烈 推荐 ) 安装 前 端 反 向 代理 服务 器 ， 例 如 nginx 或 Apache。 反 向 代理 服务 
器 能 直接 服务 于 静态 文件 ， 并 把 其 他 请 求 转发 给 应 用 的 Web 服务 器 。Web 服务 器 监听 
localhost 中 的 一 个 私有 端口 。 

。 提升 服务 器 的 安全 性 。 这 一 过 程 包含 多 项 任务 ， 目 标 在 于 降低 服务 器 被 攻击 的 概率 ， 例 
如 安装 防火 墙 、 删 除 不 用 的 软件 和 服务 ， 等 等 。 


下 















































































































































206 | 第 17 章 


不 要 手动 执行 这 些 任务 。 可 以 使 用 自动 化 框架 (例如 Ansible、Chef 或 
Puppet) 编写 一 个 部 署 脚本 。 





17.6.2 ”导入 环境 变量 


与 Heroku 和 Docker 一 样 ， 运 行 在 独立 服务 器 上 的 应 用 也 要 通过 环境 变量 做 些 设置 ， 例 如 
数据 库 连接 URL、 电 子 邮 件 服务 器 凭据 ， 等 等 。 

现在 ， 启 动 应 用 之 前 没有 Heroku 或 Docker 为 我 们 配置 这 些 变量 了 ， 因 此 我 们 要 靠 自己 。 
设置 环境 变量 的 具体 方法 依 所 用 的 平台 和 工具 而 有 所 不 同 。 为 了 统一 不 同 平台 中 配置 环 
境 变量 的 方式 ， 解 放 我 们 的 双手 ， 我 们 可 以 编写 一 段 代 码 ， 像 heroku local 和 docker- 
compose 命令 那样 ， 从 .env 文件 中 导入 环境 变量 ， 如 示例 17-14 所 示 。 这 段 代码 用 到 一 个 
Python 包 ， 名 为 python-dotenv， 我 们 要 使 用 pip 安装 它 。 在 flasky.py 脚本 中 ， 环 境 变量 
在 创建 应 用 实例 之 前 导入 ， 这 样 配置 类 才能 访问 这 些 变量 。 


示例 17-14 flasky.py: 从 .env 文件 中 导入 环境 变量 


import os 
from dotenv import Load_dotenv 


























dotenv_path = os.path.join(os.path.dirname(_ file ), '.env') 
if os.path.exists(dotenv_path): 
load_dotenv(dotenv_path) 


-env 文件 中 可 以 定义 FLASK_CONFIG 变量 ， 选 择 使 用 哪个 配置 ， 可 以 定义 DATABASE_URL 变 
量 ， 指 定 连接 数据 库 的 URL;， 还 可 以 定义 电子 邮件 服务 器 的 凭据 ， 等 等 。 如 前 所 述 ， 由 
于 .env 文件 中 包含 敏感 信息 ， 不 能 纳入 版 本 控制 。 











如 果 你 的 .env 文件 是 为 Heroku 或 Docker 准备 的 ， 那 么 要 适当 调整 一 下 ， 因 
为 根据 前 面 的 代码 ， 所 有 配置 都 将 使 用 这 个 文件 中 的 环境 变量 。 





17.6.3 配置 日 志 


在 基于 Unix 的 服务 器 中 ， 日 志 可 发 送 给 守护 进程 syslog。 我 们 可 以 专门 为 Unix 创建 一 个 
新 配置 ， 继 承 自 ProductionConfig， 如 示例 17-15 所 示 。 











示例 17-15 ”config.py: Unix 配置 示例 


class UnixConfig(ProductionConfig): 
@classmethod 
def init app(cls, app): 
ProductionConfig.init_app(app) 


# 写 入 syslog 
import logging 
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from logging.handlers import SysLogHandler 
syslog_handler = SysLogHandler() 
syslog_handler .setLevel(logging.WARNING) 
app. Logger .addHandler(syslog_handler) 


这 样 配置 之 后 ， 应 用 的 日 志 将 写 入 配置 的 syslog 消息 文件 ， 通 常 是 /var/log/messages 或 / 
varlog/syslog， 有 具体 要 看 所 用 的 Linux 发 行 版 本 。 如 果 需 要 的 话 ， 还 可 以 配置 syslog 服务 ， 
把 应 用 的 日 志 写 入 别 的 文件 或 者 发 给 其 他 设备 。 





如 果 你 从 GitHub 上 克隆 了 这 个 应 用 的 Git 仓库 ， 那 么 可 以 执行 git checkout 
179 检 出 应 用 的 这 个 版 本 。 
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其 他 资源 








恭喜 ， 你 快 读 完 本 书 了 。 和 希望 本 书 涵盖 的 话题 能 为 你 打下 坚实 的 基础 ， 让 你 开始 使 用 Flask 
开发 应 用 。 书 中 的 示例 代码 是 开源 的 ， 基 于 一 个 宽松 的 许可 协议 发 布 ， 所 以 你 可 以 在 自己 
的 项 目 中 尽情 使 用 我 的 代码 ， 即 便 是 商业 项 目 也 可 以 。 在 这 最 后 的 简短 一 章 中 ， 我 列 出 了 
一 些 建议 和 资源 ， 和 希望 能 为 你 继续 使 用 Flask 提供 一 些 帮 助 。 


18.1 使 用 集成 开发 环境 


在 集成 开发 环境 (IDE，integrated development environment) 中 开发 Flask 应 用 非常 方便 ， 
因为 代码 补 全 和 交互 式 调试 器 等 功能 可 以 显著 提升 编程 的 速度 。 以 下 是 儿 个 适合 进行 Flask 
开发 的 IDE。 


PyCharm 


JetBrains 出 品 的 IDE， 有 社区 版 (免费) 和 专业 版 (收费 )， 两 个 版 本 都 兼容 Flask 应 
用 。 可 在 Linux、macOSs 和 Windows 中 使 用 。 


Visual Studio Code 


微软 推出 的 开源 IDE。 若 想 在 开发 Flask 应 用 的 过 程 中 使 用 代码 补 全 和 调试 功能 ， 必 须 
安装 一 个 第 三 方 Python 插件 。 可 在 Linnx、macOS 和 Windows 中 使 用 。 


PyDev 
































基于 Eclipse 的 开源 IDE。 可 在 Linnx、macOS 和 Windows 中 使 用 。 


18.2 “寻找 Flask 扩 展 


本 书 中 的 示例 应 用 使 用 了 很 多 扩展 和 包 ， 不 过 还 有 很 多 有 用 的 扩展 没有 介绍 。 下 面 列 出 其 
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他 一 些 值得 研究 的 包 。 

。 Flask-Babel: 提供 国际 化 和 本 地 化 支持 。 

。 Marshmallow: 序列 化 和 反 序 列 化 Python 对 象 ， 可 在 API 中 提供 资源 的 不 同 表述 。 
。 Celery: 处 理 后 台 作 业 的 任务 队列 。 

。 Frozen-Flask: 把 Flask 应 用 转换 成 静态 网 站 。 

。 Flask-DebugToolbar: 在 浏览 器 中 使 用 的 调试 工具 。 

。 Flask-Assets: 用 于 合并 、 压 缩 及 编译 CSS 和 JavaScript 静态 资源 文件 。 

。 Flask-Session; 使 用 服务 器 端 存 储 实现 的 用 户 会 话 。 

。 Flask-SocketIO: 实现 Socket.IO 服务 器 ， 支 持 WebSocket 和 长 轮 询 。 


如 果 项 目 中 的 某 些 功 能 无 法 使 用 本 书 介绍 的 扩展 和 包 实 现 ， 那 么 你 首先 应 该 到 Flask 官方 
扩展 网 站 (http://flask.pocoo.org/extensions/) 查找 其 他 扩展 。 其 他 可 以 搜寻 扩展 的 地 方 有 
Python Package Index、GitHub 和 Bitbucket。 


18.3 ”寻求 帮助 

如 果 你 被 一 个 问题 卡 住 了 ， 仅 凭 一己 之 力 无 法 解决 ， 请 说 记 : 世界 上 有 一 群像 你 一 样 的 
Flask 开发 者 ， 他 们 很 乐意 帮助 你 。 

如 果 遇 到 Flask 或 相关 扩展 的 问题 ， 可 以 到 Stack Overflow 网 站 中 提问 。 其 他 开发 者 看 到 
你 的 问题 后 ， 如 果 知 道 如 何 解 决 ， 会 发 表 自 己 的 解答 ， 人 们 将 根据 回答 的 质量 投票 支持 或 
反对 。 作 为 提问 者 ， 你 可 以 从 中 选择 最 佳 解答 。 这 个 网 站 中 的 问题 和 解答 会 始终 保留 ， 而 
且 会 出 现在 搜索 结果 中 。 因 此 ， 在 这 个 平台 上 提问 也 算是 增加 了 有 关 Flask 的 信息 量 。 
Reddit 也 有 个 专门 针对 Flask 的 版 块 ， 这 个 版 块 很 友好 ， 你 可 以 在 上 面 提问 。 


最 后 ， 如 果 你 用 IRC 的 话 ，Freenode 上 的 #pocoo 频道 经 常 聚集 各 种 水 平 的 Flask 开发 者 ， 
有 些 人 可 能 会 一 对 一 帮 你 解决 问题 。 


18.4 参与 Flask 社 区 


如 果 没 有 社区 开发 者 的 贡献 ，Flask 不 会 如 此 优秀 。 现 在 你 已 经 成 为 社区 的 一 分 子 ， 也 从 
众多 志愿 者 的 艺 动 中 受益 ， 所 以 你 应 该 卷 虑 通过 某 种 方式 来 回馈 社区 。 如 有 果 你 不 知 从 何 和 
手 ， 可 考虑 以 下 建议 : 


。 审阅 Flask 或 者 你 最 喜欢 的 某 个 项 目的 文档 ， 提 交 修 正 或 改进 ， 
。 把 文档 翻译 成 其 他 语言 ; 

。 在 问答 网 站 上 回答 问题 ， 例 如 Stack Overflow; 

。 在 用 户 组 的 聚会 或 者 技术 大 会 上 与 同行 讨论 你 的 工作 ， 

。 为 你 使 用 的 包 修 正 缺 唤 ， 或 者 提出 改进 建议 ; 

。 开发 新 Flask 扩展 ， 开 源 发 布 ; 

。 开源 自己 的 应 用 。 


希望 你 能 使 用 上 述 或 者 其 他 有 意义 的 方式 为 社区 做 贡献 。 如 有 果 你 这 么 做 了 ， 我 由 囊 地 感谢 你 ! 
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作者 简介 

米 格 尔格 林 贝 格 〈Miguel Grinberg)， 近 30 年 开发 经 验 的 软件 工程 师 。 他 在 自己 的 博客 
中 撰写 各 类 文章 ， 内 容 涉 及 Web 开发 、 机 器 人 技术 和 摄影 ， 偶 尔 也 有 一 些 影评 。 他 生活 在 
俄勒冈 州 波 特 兰 市 。 


关于 封面 

本 书 封面 上 的 动物 是 比 利 牛 斯 效 犬 〈 家 犬 的 一 种 ) 。 这 种 大 型 西班牙 犬 的 祖先 是 一 种 名 为 
马 章 索 斯 大 的 家 畜 守 卫 犬 ， 这 种 犬 最 早 由 希腊 人 和 罗马 人 饲养 ， 现 已 灭绝 。 不 过 ， 马 章 索 
斯 犬 在 现今 多 种 常见 厂 类 的 繁育 过 程 中 都 扮演 了 重要 角色 ,例如 罗 威 那 厂 、 大 丹 犬 、 纽 芬 
兰 犬 和 卡 斯 罗 犬 。 直 到 1977 年 ， 比 利 牛 斯 攀 犬 才 被 确认 为 纯 种 犬 。 美 国 比 利 牛 斯 歼 犬 俱 
乐 部 致力 于 把 这 种 犬 作 为 宠物 在 美国 推广 。 


西班牙 内 战 结束 后 ， 原 产地 的 比 利 牛 斯 效 犬 数量 急剧 下 降 。 这 一 犬 种 能 幸存 下 来 完全 有 有 刹 
于 分 散在 全 国 各 地 的 专职 饲养 员 。 比 利 牛 斯 妆 犬 的 现代 基因 库 源 于 这 一 战 后 种 群 ， 所 以 它 
们 很 容易 得 遗传 病 ， 例 如 髋 关节 发 育 不 良 。 现 在 ， 负 责任 的 主人 郭 会 在 饲养 前 对 其 做 疾病 
检查 和 XX 光照 射 以 排除 瞬 关 节 异 常 。 

成 年 雄性 比 利 牛 斯 獒 犬 完全 长 成 后 可 重 达 200 磅 ， 所 以 饲养 这 种 狗 要 保证 充足 的 训练 和 钼 
狗 时 间 。 比 利 牛 斯 效 犬 虽然 体型 很 大 ， 而 且 曾 作为 抵挡 能 和 狼 的 猎犬 ， 但 其 性 情 温顺 ， 是 
一 种 优秀 的 家 犬 。 人 类 可 以 放心 地 让 这 种 狗 照 看 儿童 和 守护 庭院 ， 而 且 可 以 和 其 他 狗 一 起 
驯养 。 比 利 牛 斯 袭 厂 有 一 定 的 社交 能 力 和 较 强 的 领导 力 ， 在 家 庭 环 境 的 囊 陶 之 下 ,它们 已 
经 成 为 一 种 优秀 的 守护 犬 和 伙伴 。 

O’Reilly 出 版 的 图 书 ， 封 面 上 很 多 动物 都 濒临 灭绝 。 这 些 动物 都 是 地 球 的 瑰宝 。 如 果 你 想 
知道 如 何 保 护 这 些 动物 ， 请 访问 animals.oreilly.com。 


本 书 的 封面 图 片 出 自 丁 G. Wood 的 Animate Creation 一 书 。 
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Flask Web 开 发 : 基于 Python 的 Web 应 用 开发 实战 (第 2 版 ) 


作为 Python Web 开 发 的 微 框架 ，Flask 独 树 一 帜 。 它 不 会 强迫 开发 者 遵循 
预 置 的 开发 规范 ， 为 开发 者 提供 了 自由 度 和 创意 空间 。 


本 书 是 Web 开 发 入 门 经 典 教材 “ 狗 书 ”新 版 ， 针 对 Python 3 全 面 修订 。 
作者 采用 讲解 与 实例 相 结合 的 方法 ， 不 仅 介绍 了 Flask 安 装 、 使 用 等 基础 
知识 和 Flask 核 心 功能 ， 还 带领 读者 从 头 开始 一 步 步 开 发 了 社交 博客 应 用 
Flasky， 涵 盖 开发 、 测 试 到 部 署 的 Web 开 发 全 过 程 。 


目 学 习 Flask 应 用 的 基本 结构 ， 编 写 示 例 应 用 。 

目 使 用 必 备 组 件 ， 包 括 模板 、 数 据 库 、Web 表 单 和 电子 邮件 支持 。 

四 使 用 包 和 模块 构建 可 伸缩 的 大 型 应 用 。 

四 实现 用 户 身份 认证 、 用 户 角 色 和 用 户 资 料 。 

目 在 博客 网 站 中 重用 模板 、 分 页 显示 列表 以 及 使 用 富 文 本 。 

加 使 用 基于 Flask 的 REST 式 API， 在 手机 、 平 板 电 脑 和 其 他 第 三 方 客 
户 端 上 实现 可 用 功能 。 

加 学 习 运 行 单元 测试 以 及 提升 性 能 。 

目 将 Web 应 用 部 署 到 生产 服务 器 。 


米 格 尔格 林 贝 格 (Miguel Grinberg) ， 近 30 年 开发 经 验 的 软件 工程 
师 ， 以 撰写 Python 项 目 开发 的 博客 而 广 为 Python 开 发 者 所 熟知 ， 经 常 
受 邀 在 PyCon 等 大 会 上 分 享 开发 经 验 。 
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“本 书 是 学 习 Flask 的 实用 参考 。 


其 中 介绍 的 数据 库 交 互 操 作 和 不 
同 的 部 署 方 式 让 我 受益 菲 浅 。” 

一 一 Jason Myers 

思科 工程 师 ， 

PyTennessee 会 议 主 席 


“很 喜欢 这 种 项 目 驱 动 式 的 教材 ， 


每 一 步 都 十 分 清楚 ， 从 开发 到 
测试 再 到 部 署 的 全 过 程 都 有 讲 
一 一 中 文 版 读者 huron 


“给 五 星 是 因为 本 书 的 内 容 太 实 


用 了 ， 解 决 了 Flask 学 习 过 程 中 
的 痛 点 ， 是 一 本 难得 的 精炼 且 干 
货 十 足 的 技术 书 。 
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如 果 您 对 本 书 内 容 有 疑问 ， 可 发 邮件 至 contact@turingbook.com， 会 有 编辑 
或 作 译 者 协助 答疑 。 也 可 访问 图 灵 社 区 ， 参 与 本 书 讨 论 。 


如 果 是 有 关 电 子 书 的 建议 或 问题 ， 请 联系 专用 客服 邮箱 : 


ebook@turingbook.com。 
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